OAuth2 token endpoint

POST/token

Exchanges a grant for tokens (RFC 6749 §4). Supported grant types: authorization_code (with PKCE), refresh_token (rotated for public clients per RFC 9700), client_credentials, urn:ietf:params:oauth:grant-type:device_code (RFC 8628), urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693), and urn:ietf:params:oauth:grant-type:jwt-bearer (RFC 7523).

Client authentication: client_secret_basic (Authorization header), client_secret_post or private_key_jwt (client_assertion) in the body, or none (public + PKCE). DPoP-bound tokens (RFC 9449) are issued when a valid DPoP proof is presented. Responses set Cache-Control: no-store.

POST/token

curl -X POST 'https://auth.example.com/token' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=SplxlOBeZQQYbYS6WxSbIA' \
  --data-urlencode 'redirect_uri=https://app.example.com/callback' \
  --data-urlencode 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'

Response

200 OK

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "openid profile"
}

Authorization

HTTP Basic
orno credentials, for a public client

Headers

Authorizationstring
The access token, as Bearer <token> (RFC 6750 §2.1) or, for a sender-constrained token, DPoP <token> (RFC 9449 §7.1). A token minted with a cnf.jkt confirmation is only accepted together with a DPoP proof signed by that key, whichever of the two schemes carries it.
DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's cnf.jkt and cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.

Request body

application/x-www-form-urlencoded

URL-encoded token request (RFC 6749 §4).

OAuth2 token request parameters (form-encoded). grant_type is semantically required, but validation is left to the token handler so a malformed request returns a spec-shaped OAuth2 error (RFC 6749 §5.2) rather than a generic validation problem. Fields cover the authorization_code, refresh_token, client_credentials, device_code (RFC 8628), token-exchange (RFC 8693) and jwt-bearer (RFC 7523) grants.

grant_typestring
The grant type. Not constrained by an enum here so an unsupported value yields an OAuth2 unsupported_grant_type error from the handler rather than a generic validation problem.
Example"authorization_code"
codestring
Example"SplxlOBeZQQYbYS6WxSbIA"
redirect_uristring · uri
Example"https://app.example.com/callback"
code_verifierstring
Example"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
refresh_tokenstring
client_idstring
client_secretstring
client_assertion_typestring
Example"urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
at most 128 characters
client_assertionstring
at most 16384 characters
scopestring
Example"openid profile"
device_codestring
subject_tokenstring
subject_token_typestring
Example"urn:ietf:params:oauth:token-type:access_token"
actor_tokenstring
actor_token_typestring
requested_token_typestring
audiencestring
resourcestring · uri
authorization_detailsstring
assertionstring

Responses

200 OKapplication/jsonA successful token response.
A successful token response.
Headers
- Cache-Controlno-store
- DPoP-Noncestring
Body
A successful OAuth2 token response (RFC 6749 §5.1, RFC 8693 §2.2).
- access_tokenstringrequired
  Example"2YotnFZFEjr1zCsicMWpAA"
- token_typestringrequired
  Bearer or DPoP (RFC 9449) for sender-constrained tokens.
  Example"Bearer"
- expires_ininteger
  Example3600
- refresh_tokenstring
  Example"tGzv3JOkF0XG5Qx2TlKWIA"
- id_tokenstring
- scopestring
  Example"openid profile"
- issued_token_typestring
  Example"urn:ietf:params:oauth:token-type:access_token"
- authorization_detailsarray of objects
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/jsonOAuth2 error response (RFC 6749 §5.2).
OAuth2 error response (RFC 6749 §5.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
An OAuth2 error response (RFC 6749 §5.2). iss (RFC 9207) is present on authorization-endpoint error responses so clients can detect mix-up.
- errorstringrequired
  A single ASCII error code.
  Example"invalid_request"
- error_descriptionstring
  Example"client_id, redirect_uri and response_type are required"
- error_uristring · uri
- statestring
  Echoed authorization-request state (RFC 6749 §4.1.2.1).
- issstring · uri
  Issuer identifier on authorization error responses (RFC 9207).

PreviousPushed Authorization Request NextDevice Authorization Request

OAuth2 token endpoint

POST/token

Headers

Body

Body

Headers

Body

Headers

Body

Body

Headers

Body