Issue oauth token

POST/v1/oauth/token

Accepts basic

Exchange an API key for a short-lived Bearer access token (OAuth2 client-credentials grant, RFC 6749 section 4.4)

Exchanges an API key for a short-lived Bearer access token (an ES256 JWT, at most 15 min, no refresh token — RFC 6749 section 4.4.3).Show more

Exchanges an API key for a short-lived Bearer access token (an ES256 JWT, at most 15 min, no refresh token — RFC 6749 section 4.4.3). The client IS the key: client_id is the key's keyPrefix and client_secret is the WHOLE API key exactly as shown at mint (not only the part after the prefix). Authenticate by HTTP Basic (each part form-urlencoded, joined by a colon, base64 — RFC 6749 section 2.3.1) OR by client_id + client_secret in the body — never both (invalid_request). X-Api-Key and any other Authorization scheme are refused invalid_client. The body must be application/x-www-form-urlencoded, at most 16 KiB; a query string of any kind and a parameter sent twice are refused invalid_request (a secret in a URL lands in access logs). Checks run in the order request shape, client authentication, grant_type, scope, so an unauthenticated caller learns nothing about grant or scope handling. scope may only NARROW the key's scopes; absent, the token gets all of them. The token is accepted exactly as its key would be, and the key is re-checked on EVERY call made with the token: revoking the key refuses its tokens at once, and a token never holds more than the key holds now. A key in its rotation overlap gets a token that expires no later than the overlap, with the key's Deprecation / Sunset headers. 4xx answers other than 429 are RFC 6749 section 5.2's OAuthError, not ApiErrorResponse; error_description is fixed text and never echoes input. The abuse limit's 429 RATE_LIMITED (RFC 6749 names no error for it) and a platform fault's 500 are ApiErrorResponse, whose traceId is the support handle. These three answer an access token of at most 10 minutes, never past the grant's expiry, whose audience is the MCP resource; the platform API refuses it (401 TOKEN_WRONG_AUDIENCE). urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693): the AI plane only, authenticated by HTTP Basic as a configured exchange client, exchanges a client's access token (subject_token) for the downstream platform token it calls the platform with, and so learns that the grant is live. Refusals are 400 invalid_grant, invalid_target, invalid_client or unauthorized_client with a reason (OAuthError). aikonic_grant.writeOperations is computed at each exchange: the console writes ticked at consent that the tenant still has ON in writesEnabled, empty when the platform write ceiling is off; aikonic_grant.crossTenantReads names the operator cross-tenant reads ticked at consent. The downstream token lives at most 5 minutes and never past the subject token or the grant's expiry; it is never a session (no session family) and reaches only the grant's toolset's read operations its grant lists, plus, for a console grant, the commit-lite operations in writeOperations that the tenant has ON at the time of the call (else 403 SESSION_REQUIRED). An operator downstream token reaches /ops/v1 reads only, never a step-up route (it carries no MFA time). The client's token is never accepted by the platform API, and the plane never forwards it.

Request body

This operation takes no request body.

Responses

200The access token. Send it as Authorization Bearer on every other route.OAuthTokenResponse
400
RFC 6749 section 5.2 refusal — invalid_request (malformed, query string, repeated parameter, not form-encoded, both authentication methods), invalid_grant (the key's principal or tenant is no longer…Show more
RFC 6749 section 5.2 refusal — invalid_request (malformed, query string, repeated parameter, not form-encoded, both authentication methods), invalid_grant (the key's principal or tenant is no longer active), unauthorized_client (the key's IP allowlist does not admit the caller), unsupported_grant_type (a grant type not served here) or invalid_scope (a scope the key does not hold, or a malformed scope list). the MCP grants: invalid_grant (a wrong code_verifier, a reused or expired code, a spent refresh token, which revokes the grant, or an exchange the grant no longer passes, with its reason), invalid_target (a resource that does not match), authorization_pending, slow_down, expired_token and access_denied (device_code polling, RFC 8628 section 3.5)
OAuthError
401
RFC 6749 section 5.2 invalid_client — no client credential, a malformed Basic credential, an unknown, wrong, revoked, rotated-out or wrong-environment key, a client_id that is not the key's prefix, or…Show more
RFC 6749 section 5.2 invalid_client — no client credential, a malformed Basic credential, an unknown, wrong, revoked, rotated-out or wrong-environment key, a client_id that is not the key's prefix, or an unsupported authentication method (X-Api-Key, Bearer)
OAuthError
405
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more
VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
ApiErrorResponse
413
VALIDATION — the request body is larger than the surface's limit.Show more
VALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
ApiErrorResponse
414
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more
VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
ApiErrorResponse
415
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more
VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
ApiErrorResponse
429
Counted in fixed windows (default 15 min).Show more
Counted in fixed windows (default 15 min). The signup, login, password and invite routes count every attempt per client address AND per subject (the email, the username + site, or the invite token). POST /v1/oauth/token is counted three ways, none of them on client_id alone, so knowing a client_id (which is not secret) never lets anyone spend its holder's budget: oauth-token counts every attempt per client address only; oauth-token-failure counts FAILED client authentications per client address and per (client address, client_id) pair; oauth-token-issued counts tokens issued per client_id only, and only a request whose secret, grant_type and scope all passed can spend it. details.reason says which limit tripped (CLIENT_RATE_LIMITED | SUBJECT_RATE_LIMITED) and details.action which count (signup | signup-verify | login | password-forgot | password-reset | invite-accept | oauth-token | oauth-token-failure | oauth-token-issued). Retry-After is whole seconds to the end of the window, and details.retryAfterMs mirrors it. The answer is the same whether or not the account or key exists, so the limit cannot be used to enumerate accounts, and nothing the caller sent is echoed. adds three counts per client address for the MCP grant routes: oauth-authorize (GET /v1/oauth/authorize, which may fetch a Client ID Metadata Document), oauth-register (POST /v1/oauth/register) and oauth-device (POST /v1/oauth/device_authorization), and one count per MCP grant, oauth-exchange-grant (the token exchange of POST /v1/oauth/token, counted per grant after the exchange client and the subject token verified, default 120 a minute), whose details.reason is EXCHANGE_RATE_LIMITED.
ApiErrorResponse
500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

405	VALIDATION This method is not served.	not retryable
413	VALIDATION The request body is larger than this API accepts (262144 bytes).	not retryable
414	VALIDATION The request URI is longer than 8 KiB.	not retryable
415	VALIDATION Send application/json.	not retryable
429	RATE_LIMITED Too many requests of this kind for this address or account. Wait for the Retry-After interval before trying again.	retryable
500	INTERNAL An unexpected error occurred. Quote the traceId to support.	retryable