Error Handling

Authorization Errors#

Authorization errors are returned as JSON responses from the authorization endpoint with appropriate HTTP status codes. For security reasons, certain errors (like invalid client_id or redirect_uri) are not redirected to the callback URL.

{
  "error": "invalid_request",
  "error_description": "Missing client_id, redirect_uri, or scope"
}

Common error codes:

• invalid_request - Malformed request or invalid parameters (HTTP 400)

• unauthorized_client - Client not authorized for this request (HTTP 401)

• access_denied - User denied authorization or consent not finalized (HTTP 403)

• unsupported_response_type - Only code is supported (HTTP 400)

• invalid_scope - Unknown or invalid scope requested (HTTP 400)

Additional Error Context: Some errors include additional diagnostic fields:

• invalid_scopes - Array of specific invalid scopes

• invalid_tv_claims - Array of unknown true.* claims

Pushed Authorization Request Errors#

The push to /oauth/oidc/par returns the same JSON shape:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Common push errors:

• invalid_request - Not a POST (HTTP 405), no client_id anywhere, or response_type or scope missing (HTTP 400)

• invalid_client - Unknown client, wrong secret, or credentials sent in both the Authorization header and the body (HTTP 401)

• unauthorized_client - The client is public; pushing needs a client secret (HTTP 401)

A request_uri that cannot be used at the authorize endpoint is an invalid_request (HTTP 400) with one of these descriptions:

• request_uri has expired - more than 10 minutes since the push; push again

• Unknown or expired request_uri - we have no such request, usually because it expired and has been cleared; push again

• Invalid request_uri format - the value is not a request_uri we issued; send it exactly as the push returned it

• request_uri was already used - each one works once, so a reload or browser Back to the authorize URL lands here; start a new login

• client_id does not match PAR request - the client_id on the authorize URL is not the client that pushed

• Missing client_id alongside request_uri - client_id is still required on the authorize URL

See Pushed authorization requests for the flow itself.

Token Exchange Errors#

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired"
}

Common token errors:

• invalid_grant - Invalid or expired authorization code

• invalid_client - Client authentication failed

• invalid_request - Missing required parameters

• unsupported_grant_type - Only authorization_code and refresh_token supported

Token Response#

Authorization Code Grant Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 600,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def502004f8a1b2c3d4e5f6789abcdef...",
  "scope": "openid profile email trueidentity"
}

Refresh Token Grant:

POST https://your-truevault-instance.com/oauth/oidc/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token=def502004f8a1b2c3d4e5f6789abcdef... &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET

Refresh Token Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "abc123004f8a1b2c3d4e5f6789abcdef...",
  "scope": "openid profile email trueidentity"
}