Seller API OAuth tokens

Mint short-lived Bearer tokens with OAuth2 client credentials mapped to your API key when you cannot ship a long-lived secret.

Short-lived Bearer tokens for partners that prefer OAuth2 client credentials over sending a long-lived Seller API key on every request. The mint endpoint is additive — scoped API keys remain the recommended default for most integrations.

Who needs this#

Backend teams whose procurement or security policy requires short-lived access tokens, or whose gateway already speaks OAuth2 client credentials.

TL;DR#

  • Call POST /api/seller/oauth/token (also served at /api/seller/v1/oauth/token) with grant_type=client_credentials. Any standard OAuth 2.0 client-credentials client works: send a form-encoded body and the client credentials with HTTP Basic or in the body. The original JSON call keeps working.
  • client_id is the API key's id (a UUID) and client_secret is the key's secret.
  • Receive an opaque avrix_oat_* access token (about one hour TTL) and its scope.
  • Use Authorization: Bearer <access_token> on Seller API v1 routes — same scopes, environment, and IP rules as the underlying key.
  • Treat client_secret like a password. Never log it.

How this differs from standard OAuth 2.0#

Read this before pointing an OAuth library at the endpoint:

Standard (RFC 6749)Avrix
The client is registered with the authorization serverThe client is an API key: client_id is the key's id, client_secret is the key's secret. Create the key first
scope narrows the tokenscope in the request is ignored. The token carries exactly the key's scopes, returned in scope. For fewer scopes, create a narrower key (POST /keys with scopes)
Errors are 400 (401 for invalid_client) with {"error": "<code>"}Errors keep the Avrix body and status codes: 422 for a malformed request, 401 for a refused client. The body carries error and error_description; error holds the RFC 6749 code on form-encoded requests and on JSON from contract date 2026-12-01, and the message on JSON before that date
Refresh tokens are optionalThere is no refresh token. Mint a new access token before the old one expires
Tokens are often JWTsTokens are opaque avrix_oat_* strings with no readable claims
Token requests are not usually rate limitedMinting is limited per client and per source IP (429 with Retry-After)

When to use keys vs OAuth tokens#

ApproachBest for
Long-lived API keyUnattended store backends, simple rotation, few moving parts
OAuth access tokenGateways that already mint client-credentials tokens; reduced leak window

You still create the API key in the Console (or via API key management). OAuth does not replace key creation — it exchanges a key for a short-lived Bearer.

Mint a token#

The standard client-credentials call, with HTTP Basic (KEY_ID is the key's id from GET /keys or the Console key list, AVRIX_API_KEY its secret):

Bash
curl -s https://api.avrix.io/api/seller/v1/oauth/token \
  -u "$KEY_ID:$AVRIX_API_KEY" \
  -d grant_type=client_credentials

Or with the credentials in a form-encoded body:

POST /api/seller/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&client_id=00000000-0000-0000-0000-000000000000&client_secret=avrix_sk_sbx_your_key_here

Or the original JSON call, unchanged:

POST /api/seller/oauth/token Content-Type: application/json
JSON
{
  "grant_type": "client_credentials",
  "client_id": "00000000-0000-0000-0000-000000000000",
  "client_secret": "avrix_sk_sbx_your_key_here"
}
FieldMeaning
grant_typeMust be client_credentials
client_idThe API key UUID from the Console (not the secret string). Omit it when you use HTTP Basic
client_secretThe plaintext secret shown once at key creation or rotation. Omit it when you use HTTP Basic
scopeOptional and ignored: the token always carries the key's scopes

Send the client credentials one way per request: HTTP Basic or client_id and client_secret in the body. A request that sends a body secret and a Basic header is refused with 422 (invalid_request) on a form-encoded body, and on JSON from contract date 2026-12-01. Before that date a JSON body that carries client_secret is read as it always was and an Authorization header is ignored.

Successful response shape (with Cache-Control: no-store and Pragma: no-cache):

JSON
{
  "access_token": "avrix_oat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "seller:products:read seller:orders:write",
  "meta": { "requestId": "…" }
}

Use the access token on v1 routes:

Authorization: Bearer avrix_oat_…

Lifecycle and enforcement#

  • TTL. Tokens expire after about 3600 seconds. Mint a new one before expiry; there is no refresh-token grant.
  • Same key rules. Expired keys, revoked companies, non-seller companies, and IP allowlist mismatches fail the same way they would for a raw key Bearer. Mint returns 401 INVALID_CLIENT when credentials are wrong or the key/company is no longer usable.
  • Rate limits. The token endpoint throttles by source IP and by client_id. Expect 429 RATE_LIMIT_EXCEEDED with Retry-After when you mint too aggressively.
  • Deployment gate. Some deployments disable token minting. When disabled, the endpoint returns 501 — fall back to the long-lived key Bearer.

Error contract#

The mint endpoint returns the flat Avrix error envelope (code, message, requestId) with the Avrix status codes, plus the two fields OAuth 2.0 clients read: error_description (the message, on every request) and error. error holds the RFC 6749 code below on a form-encoded request and on JSON from contract date 2026-12-01; on JSON before that date it keeps the message, as it always did.

HTTPcodeerror (RFC 6749)When
422VALIDATION_FAILEDinvalid_requestMissing field, client_id not a UUID, a repeated form parameter, or credentials sent both ways
422VALIDATION_FAILEDunsupported_grant_typegrant_type other than client_credentials
401INVALID_CLIENTinvalid_clientUnknown client_id, wrong client_secret, a malformed Basic header, expired/revoked/archived key, or the company is revoked/deleted/not a seller. With HTTP Basic the response also carries WWW-Authenticate: Basic
429RATE_LIMIT_EXCEEDEDtemporarily_unavailablePer-source-IP or per-client_id mint throttle — honour Retry-After
501NOT_IMPLEMENTEDunauthorized_clientToken minting is disabled on this deployment — fall back to the key Bearer
500INTERNAL_ERRORserver_errorUnexpected failure — retry with backoff
503SERVICE_UNAVAILABLEtemporarily_unavailableToken store unavailable — retry with backoff

Using an expired or unknown avrix_oat_* token on a v1 route fails like any bad Bearer credential (401 UNAUTHORIZED).

Security practices#

  • Store client_secret in a secret manager. Never put it in browsers, mobile apps, or public repos.
  • Prefer minting close to the request path (or in a short-lived worker cache) rather than persisting access tokens across long-running processes.
  • Rotate the underlying API key on the same schedule you would without OAuth. After a rotation only the new secret mints tokens. A token minted before the rotation works as long as the old secret does: until the rotation's overlap window closes (overlapSeconds), or at once when you rotated without one, and never past its own expiry. Revoking the key ends every token minted from it.
  • Combine with an IP allowlist on the parent key when your egress is stable.

Common mistakes#

  • Sending the secret string as client_id (must be the key UUID).
  • Logging the mint request body (it contains client_secret).
  • Assuming OAuth expands or narrows scopes — the access token inherits the key’s scopes exactly, as scope in the response shows.
  • Sending HTTP Basic and client_secret in the body together — send the credentials one way.
  • Expecting a JWT with readable claims — tokens are opaque avrix_oat_* strings.

Token storage#

Access tokens are opaque and stored server-side under their SHA-256 with a one-hour lifetime; the plaintext is never persisted. The same store serves the MCP connector's user tokens, so revoking a connection or a key invalidates every token minted from it at once.

What links here

Published guides that link to this page.

Search docs

Search documentation…