postIssue access token

Authentication: This endpoint does not require a bearer token.

Issues a bearer access token for a service principal using client_credentials, or a federated human access token via urn:ietf:params:oauth:grant-type:token-exchange, and renews a human session with refresh_token. The password grant is not supported (unsupported_grant_type): human flows go through an external IdP plus token exchange. An enterprise identity backend authenticates client_credentials with private_key_jwt (RFC 7523): client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and a client_assertion signed with its issuer key, aud = this endpoint, no client_secret; 401 invalid_client for failed client authentication, including a suspended IdP or an assertion issued before its last suspension.

Refresh. Only a direct sign-in, a token-exchange without client credentials, returns refresh_token and session_expires_in (whole seconds until the session ends, 12 hours after the sign-in that started it by default); the two fields are present together or not at all. A partner token-exchange authenticated with client_id and client_secret, and client_credentials, return an access token only. Renew with grant_type=refresh_token and refresh_token (400 invalid_request without it). No client authentication is needed and request fields cannot change the stored identity or authentication evidence: the answer carries a new access token and the next refresh token, with the identity and authentication of the original sign-in, or of the session’s latest promotion. A refresh token is single-use and, by default, expires after an hour without renewal. Presenting a used one without its still-active successor ends the whole session. Every refused refresh answers 400 invalid_grant, whatever the cause: an unknown, expired, used or revoked token, or a user, identity provider or tenant MFA requirement that changed since sign-in. After it, sign in again. A 503 does not itself revoke the session, but the rotation may already have committed; recover with the persisted successor as described below.

Recovery after a lost response. Before refreshing or promoting, generate a cryptographically random 256-bit successor (yhrt_ followed by 43 base64url characters), persist it together with the current refresh token, and send it as next_refresh_token. Keep that pair until a response is safely stored. After a timeout, network error or retryable server error, send an ordinary refresh_token grant with the same pair. If rotation committed, possession of the still-active successor recovers it without another rotation or extension of the idle or absolute deadline; all session checks still run. Recovery does not apply new authentication evidence. Without a persisted successor, retrying a spent token revokes the session.

Promotion. A token-exchange that also carries the session’s current refresh_token promotes that session instead of starting a new one. This is how a session answers the insufficient_user_authentication challenge after re-authenticating. The subject_token is verified as at sign-in. It must be a fresh ID token of the same person, from the same identity provider and in the same tenant, and its auth_time must be at most 15 minutes old. The answer is a refresh’s: a new access token carrying the new authentication, the next refresh token, and session_expires_in counted to the session’s unchanged end. The presented refresh token now counts as used, and access tokens issued earlier are not upgraded. A partner token-exchange has no session to promote. Refusals answer as a refresh does: 400 invalid_grant for any refused promotion (another person, an assertion without a recent auth_time, a replayed assertion, or an unknown, expired, used or revoked refresh token), 500 server_error, or 503 temporarily_unavailable. A used refresh token ends the session, as on refresh, but only when the assertion passes the sign-in and its auth_time is recent; any other refused promotion consumes nothing. An empty refresh_token is 400 invalid_request.

Errors. Every refusal is {"error": <code>, "error_description": <text>} (RFC 6749 §5.2) with Cache-Control: no-store. Descriptions are fixed public messages; subject exchange may distinguish suspended providers, authentication predating suspension, missing provisioning and missing MFA. Refresh refusals do not expose the actor’s state. A promotion may also explain missing MFA. Internal reason codes are never returned.

Request

Required request body.

Request body schema

Field Type Required Description and constraints
audience string No
client_assertion string No minLength: 1
client_assertion_type "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" No
client_id string No
client_secret string No
grant_type "client_credentials" / "urn:ietf:params:oauth:grant-type:token-exchange" / "refresh_token" Yes
next_refresh_token string No pattern: ^yhrt_[A-Za-z0-9_-]{43}$
refresh_token string No minLength: 1
requested_token_type "urn:ietf:params:oauth:token-type:access_token" No
subject_token string No
subject_token_type "urn:ietf:params:oauth:token-type:id_token" / "urn:ietf:params:oauth:token-type:jwt" No

Additional fields are not accepted.

Request URL

POST
POST /oauth/token

Request Body

application/json
{
  "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "client_secret": "cs_live_abc123placeholder",
  "grant_type": "client_credentials"
}

Responses

Response

application/json
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiOGUyZjFhMCJ9.sig",
  "expires_in": 3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer"
}

Operation succeeded.

Response 200 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
access_token string Yes minLength: 1
expires_in integer Yes maximum: 9007199254740991; exclusiveMinimum: 0
issued_token_type "urn:ietf:params:oauth:token-type:access_token" Yes
refresh_token string No minLength: 1
session_expires_in integer No maximum: 9007199254740991; exclusiveMinimum: 0
token_type "Bearer" Yes

Additional fields are not accepted.

Response 400 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
error "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" Yes
error_description string Yes

Additional fields are not accepted.

Response 401 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
error "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" Yes
error_description string Yes

Additional fields are not accepted.

Response 500 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
error "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" Yes
error_description string Yes

Additional fields are not accepted.

Response 503 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
error "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" Yes
error_description string Yes

Additional fields are not accepted.