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

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"
}