Seller API OAuth tokens

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.

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

• Call POST /api/seller/oauth/token with grant_type=client_credentials, client_id (API key UUID), and client_secret (the plaintext key shown once at creation).
• Receive an opaque avrix_oat_* access token (about one hour TTL).
• 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.

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.

{
  "grant_type": "client_credentials",
  "client_id": "00000000-0000-0000-0000-000000000000",
  "client_secret": "avrix_sk_sbx_your_key_here"
}

Successful response shape:

{
  "access_token": "avrix_oat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "meta": { "requestId": "…" }
}

Use the access token on v1 routes:

• 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.

The mint endpoint returns the standard flat Avrix error envelope (code, message, requestId), not the RFC 6749 {"error": "..."} body:

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

• 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. Rotating invalidates minting with the old secret; in-flight access tokens expire naturally by TTL.
• Combine with an IP allowlist on the parent key when your egress is stable.

• Sending the secret string as client_id (must be the key UUID).
• Logging the mint request body (it contains client_secret).
• Assuming OAuth expands scopes — the access token inherits the key’s scopes exactly.
• Expecting a JWT with readable claims — tokens are opaque avrix_oat_* strings.

• Authentication
• API key management
• Scope matrix
• Security
• Secrets and config

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.