OAuth 2.0 Token Introspection is a mechanism that allows resource servers to query the authorization server to determine the active state and metadata of an access token in real-time. This is essential for validating tokens and enforcing fine-grained access control.

What Is Token Introspection?

Token introspection is defined in RFC 7662. It provides a standardized way for a resource server to ask the authorization server whether an access token is valid and to retrieve associated metadata such as scopes, expiration, and client info.

Why Token Introspection Matters

  • Real-time token status: Ensures tokens are still active and not revoked or expired.
  • Enforces token scope: Validates the permissions granted to the token holder.
  • Supports opaque tokens: Unlike JWTs, opaque tokens have no embedded data, requiring introspection for validation.
  • Improves security: Detects invalid or compromised tokens immediately.

How Token Introspection Works

The resource server sends a POST request to the introspection endpoint with the token to be validated.

Example cURL introspection request:

curl -X POST "https://auth.example.com/oauth2/introspect" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=ACCESS_TOKEN" \
-u "client_id:client_secret"

The response contains JSON data indicating whether the token is active and other details:

{
  "active": true,
  "scope": "read write",
  "client_id": "client123",
  "username": "[email protected]",
  "exp": 1685894400,
  "iat": 1685808000,
  "token_type": "access_token"
}
  • active: Boolean indicating if token is valid.
  • scope: Permissions granted.
  • exp, iat: Expiration and issuance timestamps.
  • username, client_id: Token owner info.

When to Use Token Introspection

  • When using opaque access tokens that cannot be decoded locally.
  • To enforce immediate revocation or session termination.
  • When token metadata is needed for authorization decisions.
  • For resource servers that require strong trust in token validation.

Token Introspection vs JWT Validation

  • JWT: Self-contained token, validated locally by verifying signature and claims, no introspection required.
  • Opaque tokens: Require introspection as token content is hidden.

Hybrid approaches use JWTs with short lifespan plus introspection for refresh tokens or enhanced security.

Security Best Practices

  • Protect introspection endpoint with strong client authentication.
  • Use HTTPS for all introspection requests.
  • Limit data returned to only necessary fields to minimize information leakage.
  • Cache introspection responses carefully to balance performance and security.

Real Case

A microservices architecture uses an API gateway that introspects incoming tokens to ensure only authorized calls pass through. If a token is revoked mid-session, introspection instantly blocks access.

Summary

Token introspection adds an important layer of real-time validation to OAuth 2.0 flows, especially when opaque tokens are used. It empowers resource servers to make informed access decisions, enhancing security and compliance.

👉 Related:

Understanding Token Revocation and When to Use It

How OAuth 2.0 Refresh Tokens Work: Best Practices and Expiry

💡 How does your system handle token validation for different token types? Do you rely on introspection, JWT validation, or a hybrid?