Skip to content

Introspection Endpoint

The OAuth 2.0 Token Introspection Endpoint is a critical component for validating tokens in OAuth 2.0 flows, particularly for opaque tokens. It allows clients to check whether a token is still valid, its associated scopes, and other metadata without requiring the client to re-authenticate the user. This endpoint is defined in RFC 7662 and is commonly used in scenarios where token revocation or dynamic validation is needed.

Mechanics of the Token Introspection Endpoint

The introspection endpoint is typically a POST request to a URL like /token/introspection or /introspect. The client sends the token and authenticates using client credentials (e.g., via Basic Auth or client secret in the request body). The server responds with a JSON object indicating the token's status, scopes, expiration time, and other attributes.

Request Structure

  • HTTP Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Body:
  • token=<token_value>
  • client_id=<client_id> (optional, depending on server configuration)
  • client_secret=<client_secret> (optional, if client authentication is required)

Response Format

A typical response includes: 

{
  "active": true,
  "scope": "openid profile",
  "exp": 1698765432,
  "iss": "https://auth.example.com",
  "sub": "user123"
}

Example: Introspecting a Token

curl -u client_id:client_secret \
  -X POST \
  -d "token=abc123xyz" \
  https://auth.example.com/token/introspection

Response: 

{
  "active": true,
  "scope": "read write",
  "exp": 1698765432,
  "iat": 1698762000
}

Use Cases

  1. Post-Logout Validation: Verify if a token is still valid after a user logs out.
  2. Dynamic Scope Checking: Ensure a token has the required scopes before granting access to a resource.
  3. Opaque Token Validation: Validate tokens issued by an Authorization Server that do not contain user claims (e.g., in OAuth 2.0 with PKCE).

Security Considerations

  • Client Authentication: The introspection endpoint must require client authentication to prevent unauthorized access.
  • Rate Limiting: Protect against brute-force attacks by limiting request frequency.
  • Sensitive Data: Avoid exposing sensitive claims (e.g., sub, exp) unless necessary.
  • Secure Transport: Always use HTTPS to encrypt communication.

Diagram: Token Introspection Flow

Client → POST /token/introspection (token, client auth)
           ↓
Authorization Server → JSON response (active, scope, etc.)

Key takeaways

  • The introspection endpoint validates tokens, checks scopes, and provides metadata.
  • Requires client authentication to ensure secure access.
  • Commonly used with opaque tokens in OAuth 2.0 flows.
  • Must be protected against abuse via rate limiting and secure transport.