OAuth 2.0 Token Introspection (RFC 7662)

Token Introspection (RFC 7662)

When an access token is an opaque string (not a self-contained JWT), the resource server cannot validate it locally. Token Introspection provides a standard API endpoint that resource servers call to check whether a token is active, who it was issued to, and what scopes it has.

Introspection Request

POST /introspect HTTP/1.1
Host: auth.example.com
Authorization: Basic czZCaGRSa3F0MzoZ...
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA&token_type_hint=access_token

Active Token Response

{
  "active": true,
  "scope": "read write",
  "client_id": "s6BhdRkqt3",
  "username": "johndoe",
  "token_type": "Bearer",
  "exp": 1709123456,
  "iat": 1709119856,
  "sub": "user-12345",
  "aud": "https://api.example.com",
  "iss": "https://auth.example.com"
}

Inactive Token Response

{
  "active": false
}

Key Response Fields

Field	Description
active	Boolean — the only required field. Indicates if the token is valid.
scope	Space-separated scopes associated with the token
client_id	Which client the token was issued to
username	Human-readable identifier for the resource owner
exp	Expiration time (Unix timestamp)
sub	Subject identifier (user ID)
aud	Intended audience for the token

JWT vs. Opaque Tokens

	JWT	Opaque Token
Validation	Local (verify signature)	Remote (introspection endpoint)
Performance	Fast (no network call)	Slower (network call per request, can be cached)
Revocation	Difficult (until expiration)	Immediate (introspection returns active=false)
Size	Large (payload included)	Small (just a reference)

When to Use Introspection

• When you need immediate token revocation
• When tokens are opaque references
• When the resource server needs authorization server metadata about the token
• Can be combined with caching (e.g., cache for 30-60 seconds) to reduce latency