Cybersecurity glossary
What is Token Introspection?
Learn what OAuth token introspection is, how resource servers query authorization servers about opaque tokens, caching trade-offs, and security practices for introspection endpoints.
Definition
Token introspection is an OAuth 2.0 protocol that lets a protected resource query the authorization server to determine the active state and metadata of an access or refresh token—commonly used when tokens are opaque rather than self-contained JWTs.
Why opaque tokens need a phone-home check
Self-contained JWTs let APIs validate locally. Opaque random tokens cannot. Token introspection gives resource servers a standard way to ask the authorization server whether a token is active and which attributes apply.
It trades a network hop for centralized control and faster revocation semantics.
Introspection request flow
Client calls the resource server
Authorization: Bearer <opaque-token> arrives at the API.
RS authenticates to the AS
Resource server uses its own client credentials or other auth to the introspection endpoint.
AS looks up the token
Checks existence, expiry, revocation, and associated metadata.
AS returns token info
JSON includes active and optional scope, client_id, exp, sub, and more.
RS authorizes the call
If active and scopes suffice, the API proceeds; otherwise it returns 401/403.
Introspection vs local JWT validation
| Topic | Introspection | JWT local validate |
|---|---|---|
| Revocation speed | Near real time | Needs short TTL or blocklist |
| Performance | Extra hop / cache | CPU verify locally |
| Claim privacy | Opaque to clients | Claims visible if token leaks |
| AS availability | Hard dependency | Weaker runtime dependency |
Security considerations
Authenticate callers
Do not let strangers introspect arbitrary tokens anonymously.
Minimize response fields
Return only claims the RS needs for authorization.
Protect the endpoint
TLS, rate limits, and monitoring for token stuffing probes.
Cache carefully
Short negative/positive TTLs aligned to risk.
Log safely
Never write full access tokens into introspection logs.
Fail closed
If introspection is down, deny or use a deliberate degraded mode.
Implementation checklist
- Require authentication for introspection endpoint clients.
- Treat active=false as definitive denial for that token presentation.
- Enforce scopes/audience from introspection before business logic.
- Keep caches short on high-risk APIs; document revocation lag.
- Monitor introspection latency and error rates as Tier-1 dependencies.
- Pair with RFC 7009 revocation so inactive state is meaningful.
- Consider hybrid designs: JWT for low-risk, introspected tokens for high-risk.
- Avoid returning refresh-token secrets or unnecessary PII in responses.
The practical takeaway
Token introspection lets resource servers validate opaque OAuth tokens through the authorization server. It enables central revocation at the cost of runtime dependency and careful caching.
Authenticate introspection callers, fail closed, keep responses minimal, and align cache TTLs with how fast you need stolen tokens to die.
Related security terms
OAuth Resource Server
API that often calls introspection to authorize requests.
OAuth Authorization Server
Issues tokens and answers introspection queries.
Token Revocation
Makes tokens inactive so introspection returns active=false.
Bearer Token
Token type commonly validated via introspection.
JWT (JSON Web Token)
Self-contained alternative that may reduce introspection need.
Frequently asked questions
What is token introspection in simple terms?
When an API receives an opaque access token, it asks the authorization server ‘is this token still good, and what permissions does it have?’ instead of decoding the token locally.
Which RFC defines it?
RFC 7662 defines OAuth 2.0 Token Introspection.
When is introspection preferred over JWTs?
When you need central, immediate revocation visibility or want to avoid leaking claims in self-contained tokens.
What does the active claim mean?
active=true means the token is valid at introspection time. active=false means expired, revoked, or otherwise not acceptable.
Who can call the introspection endpoint?
Typically authenticated resource servers or other authorized clients—not arbitrary internet callers with a stolen token alone.
How does caching affect security?
Caching introspection results improves performance but delays revocation visibility. Keep TTLs short for sensitive APIs.
Can refresh tokens be introspected?
Yes, if the authorization server supports it. Treat responses as sensitive and minimize claim exposure.
References
Explore authoritative guidance and frameworks related to token introspection.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.