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 /oauth/tokenRequest Body
{
"client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"client_secret": "cs_live_abc123placeholder",
"grant_type": "client_credentials"
}Responses
Response
{
"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.