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#
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:
| Property | Meaning |
|---|---|
| Company | The seller company the key acts as. Fixed at creation. |
| Environment | sandbox or production. Fixed at creation and not interchangeable. |
| Scopes | The operations the key may perform. Fixed at creation. |
| Expiry | Optional. 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 IPs | Source-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 type | Example prefix |
|---|---|
Live (production) | avrix_sk_live_… |
| Sandbox | avrix_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#
- Sign in to the Avrix Console and select your seller company.
- Go to Settings → Integrations → API Keys.
- Choose Create key.
- Set a descriptive name — the name appears in audit logs, so "checkout-service-prod" is more useful than "key 2".
- 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.iothose 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 /whoamiwith a sandbox key returnsproductionAccess(each step and whether it is done, andstatus:not_requested,requestedorapproved), and the403carriesdetails.productionAccess. - 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:readandseller:orders:managestay opt-in. - 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.
- 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"{
"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:
| Wrong | Why |
|---|---|
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 document | Em 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.
| Sandbox | Production | |
|---|---|---|
| Base URL | https://api.avrix.io | https://api.avrix.io |
| Catalog | Shared fixture catalog, magic SKUs | Your real agreements |
| Key material | Test keys | Real keys |
| Magic SKUs | Accepted | Rejected — SANDBOX_MAGIC_VALUE_REJECTED |
| Commercial evidence | Minimal | Full 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:
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:
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).
| Setting | Behaviour |
|---|---|
| Console-created keys | No expiry; the key does not expire by time. Retire it with rotation or revocation. |
| API-minted keys | Expire 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 it | GET /api/seller/v1/keys returns expiresAt per key (null when none). Check Settings → Integrations → API Keys for the key record in Console. |
| Advance notice | api_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)#
- Create a new key with the same scopes and allowed IPs.
- Deploy it to your services. Both keys are now valid.
- Verify the new key is serving traffic — check the Console audit log for requests attributed to it.
- Revoke the old key in the Console (or
DELETE /keys/{id}). - 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.
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 carriessecretRedacted: trueinstead ofsecret. 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 samepreviousSecretExpiresAt. - Ending the window early. A rotation without
overlapSeconds, or revoking the key, stops every older secret at once. - OAuth. The window covers
Authorization: Bearerwith the secret.POST /oauth/tokenaccepts only the current secret asclient_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:
- Revoke or in-place rotate the key. Do this first, before investigating. Availability is recoverable; leaked inventory is not.
- Create a replacement (if you revoked) and deploy it — or deploy the new secret from rotate.
- Review the audit log for the compromised key: which orders were created, which keys were pulled, from which addresses.
- Contact Avrix support (
support@avrix.ioor 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. - Add an IP allowlist to the replacement if you did not have one.
- Find the leak — rotating without fixing the exposure only resets the clock.
Troubleshooting#
401 UNAUTHORIZED#
The key was not accepted.
| Cause | Check |
|---|---|
| Malformed header | Review the header mistakes table above |
| Revoked or rotated-away secret | Console → Settings → Integrations → API Keys |
| Expired key | expiresAt on GET /keys; create a replacement key (console keys do not expire) |
| Wrong environment | GET /whoami — compare data.key.environment to what you expect |
| Truncated secret | Compare length to what the Console displayed |
| Non-ASCII characters | Re-copy from the Console, not from a document |
{
"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.
{
"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:
| Cause | Fix |
|---|---|
A production key sent with X-Avrix-Sandbox: true | Remove the header, or use a sandbox key for sandbox calls |
| A sandbox key used on a deployment where the sandbox is disabled | Use 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.
Related#
- Quickstart — first authenticated call in context
- Scope matrix — the full endpoint-to-scope mapping
- IP allowlist — allowlist validation rules and cache timing
- Sandbox to production — environment differences and cutover
- Error reference — every error code