Skip to main content

Introspect with Bearer Token

POST 
/token-srv/introspect

Token Introspection (RFC 7662)

This API validates an OAuth 2.0 access token and returns information about its active state and associated metadata. It is the recommended method for online token validation when you need to:

  • Detect revoked tokens in real-time
  • Validate token scopes before granting access to protected resources
  • Perform group and role validations that require server-side checks
  • Get complete token metadata including expiration, client ID, and user information

Security:

  • Authorization Header (Optional but Recommended): The endpoint accepts an optional Authorization header with either:
    • Basic Authentication: Basic <base64(client_id:client_secret)> - Validates client credentials
    • Bearer Token: Bearer <access_token> - Validates the bearer token signature
  • Note: While the authorization header is optional in the current implementation, RFC 7662 recommends requiring authentication. For production use, it's recommended to always provide authentication.
  • The token to introspect must be provided in the request body.

Token Validation: The endpoint validates the token and checks:

  • Token is not revoked, logged out, or renewed
  • Token has not expired
  • Client is in the token's audience
  • (If validation parameters provided) Token matches the requested scopes/roles/groups criteria

Response Format:

  • When active: true: Returns full token metadata including:
    • scope (space-separated string) and scopes (array) - All scopes associated with the token
    • roles (array) - All roles associated with the token
    • groups (array) - All groups associated with the token (if present)
    • Standard JWT claims: sub, aud, iss, exp, iat, nbf, jti
    • client_id - Client ID that issued the token
    • token_type - Type of token: "Bearer", "DPoP" (for DPoP-bound tokens), or the token_type_hint value
    • cnf - Confirmation claim (for DPoP-bound tokens, contains jkt)
    • Custom claims from the token
  • When active: false: Returns only active: false with no additional fields (as per RFC 7662)
  • The active field is set to false if:
    • Token is invalid, expired, revoked, logged out, or renewed
    • Client is not in the token's audience
    • Token not found in database
    • (If validation parameters provided) Token doesn't match the requested scopes/roles/groups AND strict validation is enabled

Request Body Validation (Optional): You can optionally provide scopes, roles, or groups in the request body to perform additional validation:

  • scopes - Array of scopes to validate
    • If strictScopeValidation: true: Token must contain ALL specified scopes
    • If strictScopeValidation: false (default): Token must contain AT LEAST ONE specified scope
  • roles - Array of roles to validate
    • If strictRoleValidation: true: Token must contain ALL specified roles
    • If strictRoleValidation: false (default): Token must contain AT LEAST ONE specified role
  • groups - Array of group validation criteria (groupId, groupType, roles)
    • If strictGroupValidation: true: Token must match ALL specified groups
    • If strictGroupValidation: false (default): Token must match AT LEAST ONE specified group
    • Each group can have strictRoleValidation for role matching within that group
  • strictValidation: true - Requires ALL of the following to be true: groupValid AND roleValid AND scopeValid
  • strictValidation: false (default) - Requires AT LEAST ONE of the following to be true: groupValid OR roleValid OR scopeValid

Important Notes:

  • When validation parameters are provided, the introspection performs additional checks beyond token validity
  • If the token is valid but doesn't match the specified scopes, roles, or groups, the response will indicate active: false (if strict validation) or active: true with returned scopes/roles that you should verify
  • For DPoP-bound tokens, the token_type will be set to "DPoP" and the cnf.jkt claim will be included
  • Anonymous users with NON_INTERACTIVE client types skip group/role validation

For more details on scope validation, see Scope Management and Permission Management.

Request​

Responses​

OK