Key points
- Defined in RFC 7662
- Used with opaque tokens (not self-contained JWTs)
- Adds a network call per request — usually cached briefly
- Returns active flag, scope, sub, client_id, exp
- Alternative to JWT validation when central revocation matters
What it is
Token introspection lets a protected API ask the authorization server, is this token still valid, and what does it grant? Defined in RFC 7662, it's the canonical way to validate opaque (non-JWT) OAuth access tokens.
How it works
The resource server POSTs the token to the AS's /introspect endpoint, authenticated as a confidential client. The AS responds with { active: true|false, scope, client_id, sub, exp, ... }. The resource server then enforces scope and subject checks before serving the request.
When buyers care
- API gateways and microservices that need authoritative, revocable token state
- Environments where signed JWT lifetimes are too long to safely cache
- Compliance regimes that require immediate revocation on offboarding
Common misconceptions
- Introspection is not for JWTs you can validate locally. If you trust the signature and claims, you don't need it.
- Don't introspect on every microservice hop. Cache the response for the token's remaining lifetime (or shorter).
FAQ
Introspection vs JWT validation — which should I pick?
Use JWTs for stateless, high-throughput APIs where short token lifetimes are acceptable. Use introspection (opaque tokens) when central revocation and fine-grained session control matter more than latency.
Is introspection slow?
It adds one network call. With smart caching (per-token, for its TTL) the overhead is negligible for most APIs.