What Token Introspection Is and When to Use It
Token introspection answers whether a token is active right now, but it is not the right tool for every JWT. Use it when revocation, opaque tokens, or central policy checks matter.
Tip
Inspect the current certificate, key, token, or endpoint output before changing deployment config; stale artifacts make fixes misleading.
Token introspection becomes relevant when "the token looks valid" is not the same as "the token should still work right now."
It is a server-to-server check defined by OAuth 2.0. A resource server asks the authorization server whether a token is active and what metadata currently applies to it.
What an introspection request looks like
The introspection endpoint is usually an authenticated POST from your backend or API gateway.
POST /oauth2/introspect
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <client credentials>
token=2YotnFZFEjr1zCsicMWpAA&token_type_hint=access_token
The response might look like this:
{
"active": true,
"scope": "read:payments write:payments",
"client_id": "payments-api",
"sub": "user_123",
"exp": 1711641000
}
The important field is active. It tells you whether the authorization server still considers the token usable.
When introspection is the right tool
- The token is opaque and your API cannot validate it locally.
- Revocation matters and you need central "still active?" answers.
- Policy can change after token issuance, and you need the authorization server to stay authoritative.
- You are debugging a provider that mixes self-contained JWTs and opaque access tokens across different clients.
When introspection is not the first thing to reach for
If you already have a self-contained JWT and a stable verification path, local validation is often faster and simpler.
That usually means:
- decode the token
- verify the signature
- validate issuer, audience, expiry, and token type
Introspection adds a network hop and central dependency. It is powerful, but it is not a free replacement for normal JWT validation.
Common failure case: introspecting the wrong token kind
Teams often introspect an ID token because it is the token they have in hand, even though the API should care about the access token.
A quick sanity check is:
ID token: proves authentication to the client
Access token: authorizes API access
Refresh token: gets new tokens, not API access
If you send the wrong token to the introspection endpoint, the response can look confusing or unhelpful even though the server is behaving correctly.
How to debug the decision cleanly
- Use JWT Decode first to see whether the token is even a readable JWT.
- Use JWT Verify when you have a self-contained JWT and want to confirm signature plus claims locally.
- Reach for introspection when the token is opaque, revocation-sensitive, or provider policy says the authorization server is the source of truth.
Questions that come up fast
Does every JWT need introspection?
No. Many JWT-based systems validate locally and never call an introspection endpoint in the normal request path.
Can introspection replace claim validation?
No. Even with introspection, your application still needs to enforce its own audience, scope, and endpoint rules.
Why would a provider use opaque tokens instead of JWTs?
Opaque tokens make revocation and central policy control simpler because the resource server cannot make final trust decisions from local claims alone.
Developer workflow
Use this guide as an operations checklist before changing certificates, tokens, DNS, or deployment settings.
- Inspect the current artifact or endpoint output before making changes.
- Change one variable at a time so a failed verification has a narrow cause.
- Keep the rollback value, expiry, and verification command in the same runbook entry.
1. current deployed artifact
2. single config or key change
3. verify endpoint/client behavior
4. record rollback and expiry details