Authentication

API keys, scopes, environments, rotation, and IP allowlists.

Every Seller API request except GET /api/seller/v1/health requires an API key. This page covers obtaining a key, using it, scoping it, restricting it by IP, rotating it, and diagnosing every authentication failure the API can return.

Key lifecycle#

Diagram

The credential#

Seller API keys are bearer tokens issued from the Avrix Console. They look like this:

avrix_sk_sbx_your_key_here

Every key begins with avrix_sk_. If your credential does not start with that prefix, it is not a Seller API key — you may have copied a display label, a key id, or a Console session token.

A key carries five properties that together determine what it can do:

PropertyMeaning
CompanyThe seller company the key acts as. Fixed at creation.
Environmentsandbox or production. Fixed at creation and not interchangeable.
ScopesThe operations the key may perform. Fixed at creation.
ExpiryOptional. Enforced when set (401 once past). Console keys have no expiry; a key created with POST /keys takes the expiresAt you send, or the creating key's. See Key expiry.
Allowed IPsSource-address restriction. Required on production keys (or a trusted workload); never set on sandbox keys in the Console. Editable after creation. See IP allowlist.

Token prefix#

New and rotated secrets encode key type in the token itself. Auth looks keys up by hash; the Console badge and GET /whoami remain the authoritative environment signal when the prefix is ambiguous.

Key typeExample prefix
Live (production)avrix_sk_live_…
Sandboxavrix_sk_sbx_…

Pre-existing keys may still show the legacy plain avrix_sk_… shape until rotated. See Environments for host and behavioural differences.

Creating a key#

  1. Sign in to the Avrix Console and select your seller company.
  2. Go to Settings → Integrations → API Keys.
  3. Choose Create key.
  4. Set a descriptive name — the name appears in audit logs, so "checkout-service-prod" is more useful than "key 2".
  5. Choose the environment. Start with Sandbox. Production keys can be created only after you sign the API Revenue Share Channel Terms under Settings → Commercial Agreements. On api.avrix.io those keys only succeed after Avrix has enabled production API access for your company — otherwise every request returns 403 PRODUCTION_ACCESS_NOT_APPROVED, and the first such refusal records your request for approval. Creating a production key without the signed terms returns 403 API_MODEL_AGREEMENT_REQUIRED. Sandbox keys are not gated. Where you stand is readable over the API: GET /whoami with a sandbox key returns productionAccess (each step and whether it is done, and status: not_requested, requested or approved), and the 403 carries details.productionAccess.
  6. Select the scopes you need. A key with no scopes is rejected on every request. The Console pre-selects the base scope set (products, preview, pull, keys write, refunds, promotions, webhooks — see Scope matrix). Deselect anything your service does not need. seller:finance:read and seller:orders:manage stay opt-in.
  7. For a production key, add at least one allowed IP (your egress address from GET /whoami-ip); the Console will not save one without it. Sandbox keys take none.
  8. Copy the secret. Console-created keys have no expiry; see Key expiry.

API Keys are available to seller companies only. If you do not see the section, confirm you have selected a seller company in the company switcher and that your Console role includes API key management.

Making an authenticated request#

Send the raw token in an Authorization: Bearer header.

curl -s -X GET "https://api.avrix.io/api/seller/v1/whoami" \
  -H "Authorization: Bearer $AVRIX_API_KEY"
JSON
{
  "data": {
    "persona": "seller",
    "sandbox": true,
    "requestEnvironment": "sandbox",
    "hasActiveBma": true,
    "company": {
      "id": "00000000-0000-4000-8000-000000000010",
      "name": "Sandbox Seller"
    },
    "key": {
      "id": "00000000-0000-4000-8000-000000000011",
      "name": "sandbox-checkout",
      "environment": "sandbox",
      "scopes": ["seller:products:read", "seller:orders:preview", "seller:orders:write"],
      "allowedIps": []
    },
    "productionAccess": {
      "status": "not_requested",
      "enforced": true,
      "requestedAt": null,
      "approvedAt": null,
      "steps": [
        { "step": "api_model_activated", "done": true },
        { "step": "production_key_created", "done": false },
        { "step": "production_access_approved", "done": false }
      ]
    },
    "capabilities": {
      "checkoutHoldEnabled": true,
      "keylessEnabled": false,
      "requireProductionAllowlistEnabled": true
    },
    "warnings": []
  },
  "meta": { "requestId": "req_01EXAMPLE" }
}

GET /whoami is the correct first call in any integration and the correct diagnostic when something is wrong. It tells you which company you are acting as (company), which environment the key belongs to (data.key.environment) and the request ran in (requestEnvironment), what you are permitted to do (data.key.scopes), which optional capabilities are enabled, and how far the company is from production access (productionAccess). The response is abridged here; the API reference lists every field. Whether the integration can sell yet is a different question, answered by GET /integration/status (see Monitoring and support).

Gateways that require short-lived tokens can exchange the key for one with the standard OAuth 2.0 client-credentials call (POST /api/seller/v1/oauth/token). It differs from a stock OAuth server in a few ways, listed at the top of OAuth tokens.

Common header mistakes#

The Authorization header is where most first-call failures originate. All of these fail:

WrongWhy
Authorization: Bearer Bearer avrix_sk_…Doubled prefix — your HTTP client may add Bearer for you
Authorization: avrix_sk_…Missing Bearer prefix
Authorization: Bearer "avrix_sk_…"Quotes are part of the value
Authorization: Bearer avrix_sk_… Trailing whitespace or newline
Pasted from a formatted documentEm dashes, ellipses, or non-breaking spaces substituted for ASCII

If you see Invalid character in header content, your token contains a non-ASCII character. Copy it again from the Console rather than from a document or chat message.

Scopes#

Scopes are explicit. A key holds exactly the scopes granted at creation, and scopes cannot be added to an existing key: create a new key with the scopes you need and rotate. A key holding seller:keys:write can create a narrower key over the API (POST /keys with scopes, a subset of its own); wider keys are created in the Console. GET /keys lists every key with its scopes, environment, allowlist, expiry and last use, and needs only seller:keys:read.

Which scope each operation accepts, which scope to choose for each job, and which older scope names are deprecated are answered in one place, the scope matrix. Its tables are generated from the API reference, so they always match what the API enforces.

A request that needs a scope the key lacks is refused with 403. On contract date 2026-12-01 and later the code is INSUFFICIENT_SCOPE; earlier dates, and requests that do not pin a date, keep FORBIDDEN (see Troubleshooting).

Grant least privilege. A catalog-sync worker needs seller:products:read and nothing else. A read-only price monitor should not hold seller:keys:pull, because that scope can pull real inventory. Use separate keys per service rather than one key with every scope — this also means a compromise can be contained by rotating one credential instead of stopping your whole storefront.

There is no published hard limit on how many Seller API keys a company may hold. Prefer least-privilege, per-service keys and retire unused ones.

Environments#

Keys are environment-scoped and not interchangeable.

SandboxProduction
Base URLhttps://api.avrix.iohttps://api.avrix.io
CatalogShared fixture catalog, magic SKUsYour real agreements
Key materialTest keysReal keys
Magic SKUsAcceptedRejected — SANDBOX_MAGIC_VALUE_REJECTED
Commercial evidenceMinimalFull set enforced

The base URL is the same for both. The key determines the environment, not the host. There is no environment parameter to get wrong, so KEY_ENVIRONMENT_MISMATCH (401) has only two causes: a production key sent with X-Avrix-Sandbox: true, or a sandbox key used on a deployment where the sandbox is disabled. See Troubleshooting.

Sandbox to production covers every behavioural difference and the cutover procedure.

IP allowlisting#

A production key needs at least one allowed IP, or a trusted workload binding in its place. A non-empty list is enforced on every key: requests from any other address are refused with 403 IP_NOT_ALLOWED. A production key with an empty list is refused with 403 ALLOWLIST_REQUIRED while GET /whoami → capabilities.requireProductionAllowlistEnabled is true, and otherwise carries the PRODUCTION_ALLOWLIST_MISSING warning. Sandbox keys need none. The full rule, in one place, is in IP allowlist.

Discover the address Avrix sees from your infrastructure:

Bash
curl -s "https://api.avrix.io/api/seller/v1/whoami-ip"

This endpoint is unauthenticated — run it from the host that will call the API, not from your laptop. Use the address it returns, not the one your cloud console reports: NAT gateways, egress proxies, and serverless platforms frequently present a different address than expected, and an allowlist built from the wrong one locks you out of your own integration.

Update the allowlist in the Console, or via the API with a key holding seller:keys:write:

Bash
curl -s -X PATCH "https://api.avrix.io/api/seller/v1/api-keys/{keyId}/allowed-ips" \
  -H "Authorization: Bearer avrix_sk_your_management_key" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_ips": ["YOUR.EGRESS.IP.HERE"] }'

Returns 204 No Content. (PATCH /keys/{keyId}/allowed-ips is the older path for the same call.) Full validation rules — accepted shapes, rejected reserved ranges, and cache timing — are in the IP allowlist reference.

Allowlisting is a defence-in-depth control, not a substitute for protecting the secret. A leaked key with an allowlist is still a leaked key.

Storing the secret#

Treat a Seller API key as you would a payment processor secret key.

Do: store it in a managed secret store; inject it as an environment variable at runtime; use separate keys per environment and per service; rotate on a schedule and on staff changes; monitor usage through the Console audit log.

Do not: commit it to source control; put it in client-side code, a mobile app, or a browser; log it, including in request dumps and error reports; send it over email or chat; share one key across services; embed it in a container image.

If a key has ever appeared in a repository, a log, a CI output, or a support ticket, treat it as compromised and rotate it — even a private repository.

Key expiry#

Expiry is enforced whenever a key has one. Set it when you create a key over the API: send expiresAt (ISO 8601 with an offset) to POST /api/seller/v1/keys. It must be at least a minute ahead (422 otherwise) and no later than the creating key's own expiry (403 otherwise).

SettingBehaviour
Console-created keysNo expiry; the key does not expire by time. Retire it with rotation or revocation.
API-minted keysExpire at the expiresAt you sent, or else at the calling key's expiry (none when the parent has none). Once past, auth rejects the key with 401 (API key expired).
Where to see itGET /api/seller/v1/keys returns expiresAt per key (null when none). Check Settings → Integrations → API Keys for the key record in Console.
Advance noticeapi_key.expiring is sent once, 14 days before the expiry, for keys meant to live longer than that; api_key.expired once it passes. Subscribe to both on a webhook endpoint, or read them from GET /events (Event reference).

Expiry is re-checked on every request (including auth-cache hits). An expired key cannot ride the ~60s auth cache.

Rotating a key#

There are two rotation mechanisms. (a) keeps both keys valid until you revoke the old one. (b) keeps the key id: without overlapSeconds it invalidates the current secret immediately, with overlapSeconds the replaced secret keeps working for that long.

(a) Create-then-retire (zero-downtime overlap)#

  1. Create a new key with the same scopes and allowed IPs.
  2. Deploy it to your services. Both keys are now valid.
  3. Verify the new key is serving traffic — check the Console audit log for requests attributed to it.
  4. Revoke the old key in the Console (or DELETE /keys/{id}).
  5. Confirm no errors follow revocation.

(b) In-place rotate (POST /keys/{id}/rotate)#

Requires seller:keys:write. Issues a new secret for the same key id. Without a body it invalidates the old secret immediately; auth caches and the revocation denylist mean other instances reject the old secret within about 60 seconds. With overlapSeconds (60 to 86400) the old secret keeps working until previousSecretExpiresAt in the response, so a rotation whose response is lost does not lock you out.

Bash
curl -s -X POST "https://api.avrix.io/api/seller/v1/keys/{keyId}/rotate" \
  -H "Authorization: Bearer avrix_sk_your_management_key" \
  -H "Idempotency-Key: rotate-{keyId}-2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "overlapSeconds": 3600 }'

The response returns the new secret once. Update every consumer before the window ends (or, without overlapSeconds, immediately): anything still using the old secret then receives 401.

  • Retry with the same Idempotency-Key. A retry does not rotate again; because the secret is never stored, the replayed answer carries secretRedacted: true instead of secret. If you never received the first answer, rotate again with a new key while the window is open: you get another new secret, and the secret you are still running on keeps working until the same previousSecretExpiresAt.
  • Ending the window early. A rotation without overlapSeconds, or revoking the key, stops every older secret at once.
  • OAuth. The window covers Authorization: Bearer with the secret. POST /oauth/token accepts only the current secret as client_secret.

You can also rotate from Settings → Integrations → API Keys in the Console (same immediate invalidation semantics).

Revocation and cache timing#

Revoke / delete / in-place rotate all mark the previous secret unusable. Propagation across instances is about 60 seconds (auth cache TTL + short-lived revocation denylist). In-flight requests that already authenticated may complete; new requests with the old secret fail once the denylist/cache catches up.

Rotate on a schedule — at least annually, and whenever someone with access leaves.

If a key is compromised#

Order matters. Do this immediately:

  1. Revoke or in-place rotate the key. Do this first, before investigating. Availability is recoverable; leaked inventory is not.
  2. Create a replacement (if you revoked) and deploy it — or deploy the new secret from rotate.
  3. Review the audit log for the compromised key: which orders were created, which keys were pulled, from which addresses.
  4. Contact Avrix support (support@avrix.io or your partner contact) with the key id and the suspected exposure window if you see unrecognised activity. Keys pulled by an attacker may be recoverable through the quarantine process if reported promptly.
  5. Add an IP allowlist to the replacement if you did not have one.
  6. Find the leak — rotating without fixing the exposure only resets the clock.

Troubleshooting#

401 UNAUTHORIZED#

The key was not accepted.

CauseCheck
Malformed headerReview the header mistakes table above
Revoked or rotated-away secretConsole → Settings → Integrations → API Keys
Expired keyexpiresAt on GET /keys; create a replacement key (console keys do not expire)
Wrong environmentGET /whoami — compare data.key.environment to what you expect
Truncated secretCompare length to what the Console displayed
Non-ASCII charactersRe-copy from the Console, not from a document
JSON
{
  "code": "UNAUTHORIZED",
  "message": "Invalid or revoked API key",
  "recoverable": true,
  "hint": "Check your API key in Settings → Integrations → API Keys",
  "doc_url": "https://docs.avrix.io/seller-api/errors#unauthorized",
  "requestId": "req_01J8..."
}

403 for a missing scope#

The key is valid but lacks a scope the operation needs. Scopes cannot be added to an existing key: create a new key with the correct scopes and rotate.

On contract date 2026-12-01 and later (pinned with X-Avrix-Api-Version, or next), the code is INSUFFICIENT_SCOPE, and details.requiredScopes lists every scope the operation accepts, preferred first. Earlier dates, and requests that do not pin a date, get FORBIDDEN with details.missingScope, exactly as below; branch on details.missingScope to tell a scope denial from any other 403 FORBIDDEN. The error playbook shows both bodies.

JSON
{
  "code": "FORBIDDEN",
  "message": "API key missing required scope: seller:keys:pull",
  "details": {
    "missingScope": "seller:keys:pull",
    "requiredScopes": ["seller:keys:pull"]
  },
  "recoverable": false,
  "hint": "Check API key scopes and permissions",
  "doc_url": "https://docs.avrix.io/seller-api/errors#forbidden",
  "requestId": "req_01J8..."
}

The example is the FORBIDDEN body of the earlier dates. A key with no scopes at all gets the same code with details.reason: "scopes_required". POST /keys returns INSUFFICIENT_SCOPE on every date when the calling key cannot grant the new key its scopes.

403 IP_NOT_ALLOWED#

Your source address is not on the key's allowlist. Call GET /whoami-ip from the failing environment to see the address Avrix observed, then add it.

KEY_ENVIRONMENT_MISMATCH#

Returned with 401. The host is the same for both environments, so it has only two causes:

CauseFix
A production key sent with X-Avrix-Sandbox: trueRemove the header, or use a sandbox key for sandbox calls
A sandbox key used on a deployment where the sandbox is disabledUse a production key there, or call a deployment that runs the sandbox

Check data.key.environment and requestEnvironment on GET /whoami with the key and headers you are sending.

Everything returns 401, including GET /whoami#

Confirm you are calling the versioned path. Unversioned paths such as /api/seller/orders issue a redirect to /api/seller/v1/orders, and many HTTP clients drop the Authorization header (and the request body on a POST) when they follow a redirect. Always call /api/seller/v1/… directly.

What links here

Published guides that link to this page.

Search docs

Search documentation…