Exchanging and refreshing tokens

Token endpoint: POST {issuer}/token, with an application/x-www-form-urlencoded body. Responses carry Cache-Control: no-store.

Client authenticationCopy Anchor Link

Grant type 1: authorization_codeCopy Anchor Link

The server's validation order: client authentication → code exists and unused → redirect_uri match → PKCE → scope filtering.

On success it returns an access token and a refresh token (the refresh token only when the scope includes offline_access), plus an id_token when openid was requested.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "scope": "openid profile email offline_access",
  "id_token": "eyJ..."
}

expires_in is determined by the redirect platform: 3600 seconds for web_server, 1800 seconds for public client platforms.

Grant type 2: refresh_tokenCopy Anchor Link

curl -X POST 'https://id.example.com/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=refresh_token' \
  -d "refresh_token=$REFRESH_TOKEN"

Rules:

• scope is optional and may only narrow: it must be a subset of the originally granted scopes; anything outside is rejected.
• Every refresh rotates: you get a new access token and a new refresh token, and the old refresh token stops working immediately. Overwrite your stored value — do not keep the old one for a "fallback retry".
• Refresh tokens are signed JWTs, but clients must not parse their contents or assume their length or format is stable.
• Refresh does not restore authorization_details: fine-grained grants hold only for the original authorization and are not carried in refreshed tokens.

Grant type 3: client_credentialsCopy Anchor Link

Available only to machine clients, for server-to-server calls, with no user involved.

curl -X POST 'https://id.example.com/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=client_credentials' \
  -d 'scope=auth:sessions:read'

• Issued tokens have no sub; the principal claim distinguishes "represents a user" from "represents an application".
• offline_access is not allowed: with no user there is no session to refresh, so requesting that scope yields invalid_scope.
• Third-party applications do not need this grant type; if you do, the product shape should be registered as machine.

Token exchangeCopy Anchor Link

First-party admin consoles can use RFC 8693 to obtain tokens for other audiences; third parties do not need it. See Token exchange.

Error response formatCopy Anchor Link

The token, revocation and introspection endpoints follow RFC 6749 §5.2, not the unified envelope used by the console APIs:

{
  "error": "invalid_grant",
  "error_description": "The authorization code has already been used"
}

Rate limiting returns 429 with the unified envelope and a Retry-After header; see Error codes.