The Token Introspection Endpoint
RFC 7662 defines the introspection endpoint, a protected /introspect route on the authorization server that lets a resource server submit a token and receive back a JSON response describing whether it's currently active, and if so, its scope, client_id, exp, and other metadata. This is the standard mechanism for validating opaque tokens, which have no embedded claims of their own, but it's also used with JWTs when an API needs a real-time, authoritative answer rather than trusting a locally cached signature, for example to catch a token that was revoked seconds ago but hasn't yet expired. Because introspection requires the resource server to authenticate itself to the authorization server, it also prevents random unauthenticated parties from probing which tokens happen to be valid.
Cricket analogy: It's like a stadium's turnstile scanner calling the BCCI's central ticketing system in real time before letting a fan through, rather than trusting a printed ticket's ink alone, catching a ticket that was refunded five minutes ago.
POST /introspect HTTP/1.1
Host: auth.example.com
Authorization: Basic cmVzb3VyY2Utc2VydmVyOnMzY3IzdA==
Content-Type: application/x-www-form-urlencoded
token=v1.MzQ4YTk3ZjEtNGQ3YS05YzNlLTJmOGI1YTFlMGQ3Nw
// Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"scope": "orders.read orders.write",
"client_id": "mobile-app-ios",
"sub": "user_8842",
"exp": 1752163200,
"token_type": "Bearer"
}
// If revoked or expired, only { "active": false } is returned.The Revocation Endpoint
RFC 7009 defines the revocation endpoint, which lets a client proactively invalidate a token before its natural expiry, typically called during logout. Submitting either an access token or a refresh token to /revoke tells the authorization server to mark it, and by convention any refresh tokens derived from the same grant, as no longer usable. This matters because logging out of just the client's local session (clearing a cookie or deleting local state) does nothing to invalidate the underlying tokens; if a stolen refresh token exists somewhere else, a local-only logout leaves it fully functional. True logout requires calling revocation so the authorization server's own record of validity changes.
Cricket analogy: It's like a stadium proactively deactivating a season pass's chip the moment a member cancels their membership, rather than just removing the pass from a fan's own wallet app while the physical chip still opens turnstiles.
Revocation and JWT Limitations
Revocation exposes the fundamental tension with self-contained JWT access tokens: because resource servers verify JWTs locally by signature, calling /revoke on the authorization server doesn't automatically stop those resource servers from continuing to accept the token until it naturally expires, unless they're also configured to check a deny-list or call introspection for sensitive operations. This is why systems that need strong, immediate revocation guarantees for access tokens either keep JWT lifetimes very short (minutes), pair JWTs with a lightweight revocation deny-list checked on high-value actions, or fall back to opaque tokens with mandatory introspection where immediate revocation truly matters, such as financial transfers or account deletion.
Cricket analogy: It's like an old-style printed match ticket that a scalper can still get gate staff to accept even after the box office marks the seat as refunded, unless every gate also phones the box office before letting someone in.
Do not assume that calling /revoke instantly stops all access if your resource servers verify JWTs locally by signature alone. For high-value operations, pair short JWT lifetimes with either introspection or a checked deny-list to get true real-time revocation guarantees.
- The introspection endpoint (RFC 7662) lets a resource server ask the authorization server in real time whether a token is active, including its scope and expiry.
- The revocation endpoint (RFC 7009) lets a client proactively invalidate an access or refresh token, typically as part of logout.
- Revoking a refresh token conventionally revokes the whole family of tokens derived from the same grant.
- Clearing local session state (cookies, local storage) does not itself invalidate tokens; true logout requires calling the revocation endpoint.
- JWTs verified locally by signature don't automatically respect server-side revocation until they naturally expire, unless paired with introspection or a deny-list check.
- High-value operations (financial transfers, account deletion) should use short-lived JWTs plus introspection, or opaque tokens, for real-time revocation guarantees.
- Introspection requires the calling resource server to authenticate itself, preventing unauthenticated probing of which tokens are valid.
Practice what you learned
1. What does the token introspection endpoint (RFC 7662) primarily provide to a resource server?
2. Why doesn't calling the /revoke endpoint immediately stop all resource servers from accepting a JWT access token?
3. What typically happens when a client revokes a refresh token via the revocation endpoint?
4. Why is clearing a client's local cookies or local storage on logout not sufficient for true security-critical logout?
5. What is a recommended strategy for achieving real-time revocation guarantees on high-value operations while still using performant JWTs?
Was this page helpful?
You May Also Like
Access Tokens and JWTs
Access tokens are the credentials a client presents to a resource server, and JWTs are the most common self-contained format for encoding them.
Refresh Tokens
Refresh tokens let a client obtain new access tokens without forcing the resource owner to re-authenticate, and how they're issued and rotated is central to OAuth 2.0 security.
Token Storage Best Practices
Where and how a client stores access and refresh tokens is often the deciding factor in whether an OAuth 2.0 integration is actually secure in practice.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics