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) withgrant_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_idis the API key's id (a UUID) andclient_secretis the key's secret.- Receive an opaque
avrix_oat_*access token (about one hour TTL) and itsscope. - Use
Authorization: Bearer <access_token>on Seller API v1 routes — same scopes, environment, and IP rules as the underlying key. - Treat
client_secretlike 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 server | The 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 token | scope 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 optional | There is no refresh token. Mint a new access token before the old one expires |
| Tokens are often JWTs | Tokens are opaque avrix_oat_* strings with no readable claims |
| Token requests are not usually rate limited | Minting is limited per client and per source IP (429 with Retry-After) |
When to use keys vs OAuth tokens#
| Approach | Best for |
|---|---|
| Long-lived API key | Unattended store backends, simple rotation, few moving parts |
| OAuth access token | Gateways 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):
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
{
"grant_type": "client_credentials",
"client_id": "00000000-0000-0000-0000-000000000000",
"client_secret": "avrix_sk_sbx_your_key_here"
}
| Field | Meaning |
|---|---|
grant_type | Must be client_credentials |
client_id | The API key UUID from the Console (not the secret string). Omit it when you use HTTP Basic |
client_secret | The plaintext secret shown once at key creation or rotation. Omit it when you use HTTP Basic |
scope | Optional 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):
{
"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 withRetry-Afterwhen 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.
| HTTP | code | error (RFC 6749) | When |
|---|---|---|---|
| 422 | VALIDATION_FAILED | invalid_request | Missing field, client_id not a UUID, a repeated form parameter, or credentials sent both ways |
| 422 | VALIDATION_FAILED | unsupported_grant_type | grant_type other than client_credentials |
| 401 | INVALID_CLIENT | invalid_client | Unknown 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 |
| 429 | RATE_LIMIT_EXCEEDED | temporarily_unavailable | Per-source-IP or per-client_id mint throttle — honour Retry-After |
| 501 | NOT_IMPLEMENTED | unauthorized_client | Token minting is disabled on this deployment — fall back to the key Bearer |
| 500 | INTERNAL_ERROR | server_error | Unexpected failure — retry with backoff |
| 503 | SERVICE_UNAVAILABLE | temporarily_unavailable | Token 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_secretin 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
scopein the response shows. - Sending HTTP Basic and
client_secretin the body together — send the credentials one way. - Expecting a JWT with readable claims — tokens are opaque
avrix_oat_*strings.
Related#
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.