2026-09-30 · 8 min read
- oauth
- tokens
- security
Token introspection (RFC 7662) lets a resource server ask the authorization server whether a token is currently active. It is the right tool for opaque tokens and for revocation that a local signature check cannot see.
The endpoint returns a JSON object. The active boolean is the decision. HTTP 200 with active false means the token is not usable. It does not mean the introspection call itself was unauthorized.
Authenticate the caller, then present the token
The introspection endpoint is its own protected resource. The resource server authenticates with a registered credential: a client secret, mutual TLS, or a private-key JWT, according to the authorization server. The user's access token is the body parameter named token, not a substitute for that credential.
- Pin the introspection URL from trusted metadata.
- Store the resource-server credential in a secret manager.
- Send token_type_hint only as a hint.
- Reject endpoints supplied by the token or by an untrusted document.
Read active before any other claim
When active is false, the server should omit further details. Do not invent a reason from a missing scope or a missing username. When active is true, still check issuer, audience, expiration, and token type against the API that received the call.
A token can be active for a different resource. Audience is the resource server's check. Introspection did not grant access to every API that shares an authorization server.
Bound caches and define revocation delay
Caching an active true result reduces load and also delays revocation. Cap the cache by the token exp and by a shorter product limit. Cache active false only briefly, and key the entry to the token so a new token is not rejected with an old denial.
Document the maximum revocation delay in the threat model. If that delay is unacceptable, introspect on each call or use a revocation signal the resource server already receives.
Keep JWTs and opaque tokens on their paths
A signed JWT can be validated locally for signature, issuer, audience, and time, then introspected when revocation or opaque claims matter. Introspecting every JWT at a remote endpoint adds a runtime dependency and a privacy copy of the token.
Do not log the token, the Authorization header, or a reversible hash of the token. Log a correlation id, the active flag, the HTTP status, and the credential identity of the resource server.
Exercise failure with synthetic fixtures
Use Flashman's JWT decoder for synthetic tokens, the JSON formatter for introspection bodies, the timestamp converter for exp and cache deadlines, the URL parser for the endpoint, and diff for response fixtures.
Test active true, active false, HTTP 401 to the introspection endpoint, the wrong audience, an expired token, a revoked token, a stale cache, and a metadata URL that points at an unexpected host.