Token Introspection and Revocation

Analogy categoryAnalogies

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.

http

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.