Token Introspection
Token introspection lets a resource server ask the authorization server whether an opaque token is active and what it grants, centralizing revocation and policy.
Definition
Token introspection is an OAuth 2.0 endpoint defined by RFC 7662 where a protected resource submits a token and receives metadata about it, including whether it is active, its scopes, client, subject, and expiry.
Context and scope
Use it when access tokens are opaque or when the resource server must see revocation and scope changes immediately rather than trusting a self-contained token until it expires.
Common misconceptions
- Introspection validates the token signature; it is a server-side lookup, not a cryptographic check
- Any caller may introspect any token; the endpoint must authenticate and authorize clients
- Introspection must run on every request; short-lived caching is usually acceptable
Anti-patterns
- Exposing the introspection endpoint to public clients or the internet without authentication
- Caching introspection results longer than the token's remaining lifetime
- Ignoring the aud and scope fields after receiving an active response
Related concepts
Related examples
Authoritative source
The problem it solves
Self-contained tokens such as JWTs can be verified locally, but they cannot be un-issued. An opaque token carries no claims, so the resource server must ask the authorization server what it means. Introspection is that question, standardized so different vendors answer in the same shape.
How it works
The resource server sends POST /introspect with token=... and authenticates itself, typically with client credentials over TLS. The response includes active, plus fields such as scope, client_id, username, token_type, exp, iat, aud, and iss when active. An inactive or unknown token returns {"active": false} and nothing else, which avoids leaking whether a token ever existed.
The resource server must still enforce authorization: an active token with the wrong audience or missing scope is not access. Cache the result for a short period bounded by exp, and key the cache by a hash of the token, never by the raw value in logs.
When to use it
Introspection fits opaque access tokens, reference tokens, and deployments where revocation must take effect within seconds. It also helps when scopes or tenant bindings change dynamically. For high-volume, short-lived JWTs with a trusted issuer, local validation avoids a network hop on every request.
Trade-offs
Every introspection call adds latency and creates a hard dependency on the authorization server. Outages become API outages unless results are cached or a fallback policy exists. Centralized introspection also concentrates load and becomes a privacy-sensitive log of token usage, so minimize retention.
Example and misconceptions
A gateway receives an opaque token, introspects it, and learns active: true, scope: "orders:read", aud: "orders-api", exp in 60 seconds. It caches the decision for 30 seconds and rejects a request for orders:write despite the token being active.
The common misconception is that introspection returns identity and permissions only. It returns metadata; the resource server still decides what that metadata permits.
Related concepts: JSON Web Token (JWT), Token Revocation, and OAuth Scopes.