Token Introspection & Revocation in OAuth 2.0
How a resource server asks "is this still good?" — and how a token can be killed the instant it becomes dangerous.
Picture a company office building where every employee badge works by simply flashing a barcode at the door. Two questions matter enormously to whoever runs that building’s security desk. First: right now, at this exact moment, is this particular badge still active, or was it already deactivated after someone got fired last week? Second: if a badge is ever reported lost or stolen, can security instantly kill it, rather than waiting for it to naturally expire at the end of the month? Those two questions — “is it still good?” and “can we kill it right now?” — are exactly what token introspection and token revocation answer in OAuth 2.0, and together they turn access tokens from a fire-and-forget credential into something a system can actively manage throughout its entire life.
1What Are Introspection and Revocation?
These two ideas are companions, not rivals — one asks a question about a token’s current state, the other changes that state permanently. Understanding them together makes each one clearer.
Token introspection is a standardized way for a resource server, or any other authorized party, to ask the authorization server a simple question about a specific token: “Is this still valid, and if so, what does it allow?” The authorization server responds with the token’s current status, along with useful details like its scope, its owner, and its expiry time.
Token revocation, by contrast, is a standardized way to actively kill a token before its natural expiry time arrives — turning a token that would otherwise remain valid for another hour, day, or month into something instantly unusable, on demand, whether triggered by a user clicking “disconnect this app” or a security team responding to a suspected breach.
Introspection is like calling a credit card company’s fraud line and asking, “Is this specific card number still active, and what is its spending limit?” Revocation is like reporting that same card as stolen and having the company cancel it on the spot, right there on the phone call, rather than waiting for the card to naturally expire at the printed date on its front. One is a status check; the other is a decisive action — and a well-run credit card company, like a well-run authorization server, needs to support both.
Both concepts exist because access tokens, once issued, do not automatically know about events that happen after the fact — a user changing their mind, an administrator detecting suspicious activity, or an application being uninstalled. Introspection and revocation are the two tools that let a system stay in control of tokens throughout their entire working life, not just at the moment they are first created.
Both mechanisms are formally defined as their own dedicated specifications — RFC 7662 for token introspection and RFC 7009 for token revocation — meaning a resource server or client built by one team can reliably talk to an authorization server built by an entirely different team, using the same standard request and response shapes, without custom integration work.
A ten-year-old could picture it this way: introspection is like asking the school office, “Is this hall pass still valid, and which classrooms can this student visit with it?” Revocation is like the office deciding to void that hall pass immediately, right in the middle of the school day, so it stops working the instant a teacher checks it next, even though the pass was originally printed to last until the final bell.
2Architecture & Components
Introspection and revocation each add one dedicated endpoint to the authorization server, and both endpoints are used by different participants for different purposes.
Introspection Endpoint
Called by a resource server (or a trusted intermediary) whenever it needs to check a token’s current status and scope, especially useful for opaque tokens that carry no readable information on their own.
Revocation Endpoint
Called by a client — or an internal admin tool — to actively invalidate a specific access token or refresh token, immediately, regardless of how much time remains until its natural expiry.
Authorization Server
The single source of truth behind both endpoints — it holds the real, current record of every token’s status and is the only party genuinely capable of answering “valid?” or performing an actual kill.
Resource Server
The party most commonly calling the introspection endpoint, since it is the one deciding, on every incoming request, whether a token deserves access to protected data.
flowchart LR
RS["Resource Server"] -->|1: Sends token to check| IE["Introspection Endpoint"]
IE -->|2: Returns active/inactive + scope| RS
U["User or Admin"] -->|3: Requests disconnect| C["Client App"]
C -->|4: Sends token to kill| RE["Revocation Endpoint"]
RE -->|5: Confirms revoked| C
IE -.->|Shares same token store| RE
Notice that both endpoints ultimately consult, or update, the exact same underlying token record kept by the authorization server. This shared source of truth is what makes the two mechanisms consistent with each other — a token revoked through the revocation endpoint will, the very next moment, be reported as invalid by the introspection endpoint, because both are simply different windows into the same authoritative record.
Neither endpoint is meant to be called by just anyone. Both are protected — typically requiring the calling client or resource server to authenticate itself first — because the information returned (whether a token is valid, and for whom) and the action performed (killing a live credential) are both sensitive operations that should never be exposed to arbitrary, unauthenticated callers.
3Internal Working: What Happens Inside Each Endpoint
Both endpoints are, at their core, deliberately simple — a token goes in, and a clear answer or confirmation comes back out.
Calling the introspection endpoint involves sending the token in question, along with the caller’s own credentials proving it is allowed to ask. The authorization server looks the token up in its internal records and responds with a structured answer — most importantly a simple active field set to true or false, plus, when active, additional details like the token’s scope, its intended audience, its expiry timestamp, and which user or client it belongs to.
Calling the revocation endpoint involves sending the specific token to be killed, again with proper authentication. The authorization server marks that token — and, depending on implementation, sometimes any related tokens issued alongside it, such as revoking a refresh token together with its currently active access token — as permanently invalid in its records. The endpoint’s response is deliberately minimal, typically just a success confirmation, without revealing extra details about the token that was just destroyed.
| Aspect | Introspection | Revocation |
|---|---|---|
| Purpose | Check current status and details | Actively invalidate immediately |
| Typical caller | Resource server | Client application or admin tool |
| Effect on the token | None — read-only check | Permanent — token becomes unusable |
| Response detail | Rich (scope, owner, expiry) | Minimal (simple confirmation) |
This design matters most for opaque tokens, discussed at length elsewhere in this series, which carry no readable information of their own. For those tokens, introspection is not an optional convenience — it is the only way a resource server can learn anything about the token at all. For self-contained JWT tokens, a resource server can often read basic claims like expiry directly from the token itself, but introspection still matters for confirming that a JWT has not been revoked early, since a signature alone cannot reflect a revocation that happened after the token was issued.
Introspection is like a bouncer radioing the main office to ask, “Is wristband number 4471 still valid, and what areas does it cover?” and getting back a detailed answer. Revocation is like the main office pressing a button that deactivates wristband 4471 specifically, the moment its owner is caught causing trouble — after which any bouncer radioing in about that same wristband number will immediately be told it no longer works, no matter how new or undamaged the physical wristband still looks.
4Data Flow & Lifecycle
Introspection typically happens quietly, over and over, throughout a token’s entire active life. Revocation happens rarely, but decisively, and permanently changes that life’s trajectory the moment it occurs.
sequenceDiagram
participant U as User
participant C as Client App
participant AS as Authorization Server
participant RS as Resource Server
C->>RS: Calls API with access token
RS->>AS: Introspect token
AS->>RS: active=true, scope=orders.read
RS->>C: Returns protected data
Note over U,AS: Later, user disconnects the app
U->>C: Clicks "Disconnect this app"
C->>AS: Revoke token
AS->>C: Confirms revoked
Note over C,RS: Any further use of the same token
C->>RS: Calls API with the same (now revoked) token
RS->>AS: Introspect token
AS->>RS: active=false
RS->>C: 401 Unauthorized
This diagram shows exactly why the two mechanisms matter together. Before the disconnect action, every introspection call confirms the token is alive and well. The moment revocation happens, nothing about the token itself physically changes — no bits inside it are altered — but the authorization server’s internal record now says otherwise, and every future introspection call reflects that new reality instantly.
A useful lifecycle to keep in mind: a token is issued, then repeatedly introspected (directly or via a cached local check) throughout its active use, and eventually meets one of two endings — either it simply expires on schedule, having never been introspected as anything but valid, or it is explicitly revoked partway through its life, after which every subsequent introspection call reports it as inactive for the remainder of what would have been its natural lifetime.
5Advantages, Disadvantages & Trade-offs
Adding these two capabilities makes a token-based system genuinely more controllable — but that control is not free, and different token formats feel the cost differently.
Advantages
- Gives a system a real “off switch” for access, independent of a token’s original expiry time
- Lets opaque tokens carry rich, current status information without embedding anything readable in the token itself
- Provides a standardized, interoperable way for different vendors’ resource servers and authorization servers to communicate
- Strongly limits the damage window when a token is compromised, once revocation is triggered
Disadvantages & Trade-offs
- Introspection on every request adds a network round trip and latency, unless carefully cached
- Revocation for self-contained JWTs is inherently harder, since the token’s signature remains technically valid until introspection or a denylist check catches the mismatch
- Running dedicated endpoints adds operational load and requires its own uptime, monitoring, and scaling considerations
- Over-aggressive caching of introspection results to reduce latency can delay how quickly a revocation actually takes effect in practice
This is exactly where the earlier opaque-versus-JWT trade-off, discussed in relation to access tokens generally, resurfaces in sharper focus. A system built entirely on opaque tokens gets instant, guaranteed revocation for free, since every check already goes through the authorization server. A system built on self-contained JWTs must deliberately add extra infrastructure — typically a revocation denylist checked alongside signature verification — specifically to recover the instant-revocation property that opaque tokens provide naturally, trading away some of the “no network call needed” benefit that made JWTs attractive in the first place.
6Security
Introspection and revocation are themselves security-sensitive operations, and protecting them properly is just as important as the protections they provide for the tokens they manage.
Authenticate the Caller
Both endpoints must verify that whoever is calling them — a resource server or a client — is itself a legitimate, registered participant, never accepting anonymous requests.
Avoid Information Leakage
Introspection responses should reveal only what the calling party genuinely needs, avoiding unnecessary exposure of unrelated user details beyond scope, expiry, and basic ownership.
Fast Revocation Propagation
Any caching layer sitting between a resource server and the introspection endpoint should use a short enough time-to-live that a real revocation takes effect within an acceptable window, not minutes or hours later.
Cascade Related Tokens
Revoking a refresh token should typically also revoke any access tokens issued alongside it, closing off every credential tied to the same compromised session, not just one piece of it.
A frequent, subtle mistake is a resource server that introspects a token once at the start of a long-lived internal process — say, a background job expected to run for several hours — and then never checks again for the remainder of that process. If the token is revoked partway through, the job keeps happily using it as though nothing changed, since it never asks the question a second time. Long-running processes should re-check token validity periodically, not just once at the very start.
It is also worth noting that revocation, while powerful, cannot retroactively undo actions already taken with a token before it was revoked — it only prevents future use. This is why fast detection and fast revocation together matter so much: the value of revocation lies entirely in shrinking the window during which a compromised token can cause additional harm, not in reversing harm already done.
7Monitoring, Logging & Metrics
Because introspection runs constantly and revocation runs rarely but critically, each deserves its own distinct monitoring approach.
What Good Monitoring Looks Like
Tracking introspection call volume and latency reveals whether the endpoint is becoming a bottleneck as traffic grows, while tracking revocation event counts, and specifically who or what triggered each one — a user action, an admin decision, or an automated fraud-detection system — helps distinguish routine account hygiene from a genuine, active security incident unfolding in real time.
| Metric | What It Reveals |
|---|---|
| Introspection call volume & latency | Whether the endpoint can keep up with resource-server request rates |
| Introspection cache hit rate | How much load is being absorbed by caching versus hitting the authorization server directly |
| Revocation event count, by trigger source | Distinguishes routine disconnects from admin-driven or automated security responses |
| Time between compromise detection and revocation | How effectively the whole system limits the damage window of a stolen token |
A sudden, unexplained spike in revocation events — especially ones triggered by automated fraud-detection systems rather than ordinary users — is one of the clearest possible signals that something has gone wrong elsewhere in the system, and deserves immediate attention rather than being treated as routine noise.
8Design Patterns & Anti-patterns
A handful of well-tested patterns make introspection and revocation genuinely effective at scale, while a few recurring anti-patterns quietly undermine the entire point of having them.
The Pattern
Deploying self-contained JWT access tokens with no revocation strategy at all, assuming signature validity alone is sufficient proof that a token should still be trusted.
Why It Fails
A stolen or otherwise compromised JWT remains fully usable for its entire original lifetime, with no way to cut it off early, no matter how quickly the compromise is discovered.
The Fix
Pair JWTs with a lightweight revocation denylist, checked alongside signature verification, or favor deliberately short JWT lifetimes so any gap in revocation ability closes on its own relatively quickly.
The Pattern
Caching introspection results for an excessively long time to reduce network calls, without considering the effect on revocation responsiveness.
Why It Fails
A token revoked in response to a genuine security incident may continue working, from the resource server’s perspective, until the stale cached result expires — potentially minutes after the revocation was supposed to take effect.
The Fix
Choose a cache lifetime that is deliberately short enough to keep revocation response times acceptable for the system’s actual risk tolerance, and consider supplementing the cache with an active invalidation signal for high-severity revocation events.
A healthy, widely adopted pattern is centralizing both endpoints behind a well-monitored, highly available service, since every other part of the system depends on it responding quickly and correctly — a slow or unreliable introspection endpoint effectively becomes a slow or unreliable authorization layer for every protected API relying on it. Another sound pattern is exposing a self-service “connected apps” management page for end users, backed directly by the revocation endpoint, so users themselves can disconnect an app’s access at will, without needing to contact support.
9Best Practices & Common Mistakes
Real-world teams building or integrating against these two endpoints tend to run into the same practical mistakes over and over.
Cache Introspection Sensibly
Cache results for a short, deliberately chosen window to balance performance against revocation responsiveness — never cache indefinitely.
Assume JWTs Never Need Revocation
Just because a JWT can be validated locally does not mean it should be trusted forever — build in a revocation strategy from the start rather than bolting one on after an incident.
Revoke Related Tokens Together
When revoking a refresh token, also revoke its associated access tokens, and vice versa where the specification and implementation allow it, to fully close a compromised session.
Expose These Endpoints Publicly Without Auth
Never allow unauthenticated callers to introspect or revoke arbitrary tokens — both endpoints must verify the caller’s own identity before acting.
Re-check Long-Running Processes
Periodically re-introspect tokens used by long-lived background jobs, rather than trusting a single check made hours earlier at the process’s start.
Treat Revocation as Reversible
Design revocation as a one-way, permanent action for that specific token — never build a “undo revocation” feature, since a genuinely compromised or intentionally disconnected token should never quietly come back to life.
When building a “disconnect this app” feature for end users, call the revocation endpoint immediately and confirm success back to the user in the interface, rather than simply deleting a locally stored token reference and assuming the authorization server will figure out the rest on its own.
10Real-World & Industry Examples
Introspection and revocation quietly power some of the most familiar account-security features people interact with regularly, often without realizing the standardized machinery running underneath.
Google’s “Third-Party Apps & Services” Page
The account settings page where users see every app connected to their Google account, and can click to remove access, is a direct, user-facing front end for the revocation endpoint — a single click there instantly kills the underlying token, no matter how much of its original lifetime remained.
API Gateways Using Centralized Introspection
Large-scale API gateway products commonly centralize token introspection for every microservice behind them, checking each incoming request’s token once at the gateway layer rather than requiring every individual downstream service to implement its own introspection logic separately.
GitHub’s Personal Access Token Management
GitHub’s token management interface, which lets a developer see every active token tied to their account and revoke individual ones instantly, reflects the same underlying revocation pattern, giving users direct, granular control over which specific credentials remain valid.
Enterprise Single Sign-On Providers
Enterprise identity providers used by large organizations frequently combine automated introspection checks with immediate revocation triggered by HR or IT systems — for example, automatically revoking every active token tied to an employee’s account the moment their employment record is marked as terminated.
11Frequently Asked Questions
No — introspection is a read-only operation. It simply reports the token’s current status and details without modifying the token or its underlying record in any way.
No — the revocation endpoint requires the calling client to authenticate itself, and it will only revoke tokens that legitimately belong to that authenticated client, preventing one application from maliciously or accidentally invalidating another application’s tokens.
An opaque token’s validity is looked up fresh from the authorization server’s own record on every check, so a revocation is reflected instantly. A JWT’s signature remains technically valid on its own until its natural expiry, so revoking it early requires additional infrastructure, typically a denylist checked alongside signature verification, to actually catch the fact that it was revoked.
It depends on the specific authorization server’s implementation, though many well-designed systems do cascade the revocation to close off the entire session at once. This behavior is worth confirming directly against a given provider’s documentation rather than assumed universally.
In principle, immediately — the authorization server’s own record updates the moment revocation is processed. In practice, any caching layer between a resource server and the introspection endpoint introduces a small delay equal to that cache’s time-to-live, which is why choosing a sensible, short cache duration matters for genuinely fast revocation.
12Summary and Key Takeaways
What to Remember
- Introspection answers “is this token still good, and what does it allow?” — a read-only status check most essential for opaque tokens that carry no readable information on their own.
- Revocation answers “can we kill this token right now?” — an active, permanent action that ends a token’s usable life before its natural expiry.
- Both are standardized: introspection under RFC 7662 and revocation under RFC 7009, letting different vendors’ systems interoperate reliably.
- Both endpoints must themselves be protected — authenticated callers only, minimal information exposure, and careful design against becoming an attack surface of their own.
- Opaque tokens get instant revocation for free; self-contained JWTs need extra infrastructure, typically a denylist, to recover that same instant-kill property.
- Caching introspection results improves performance but delays revocation — the two must be balanced deliberately, not left to a default setting nobody revisits.
- This is everyday, user-facing reality — every “disconnect this app” button on Google, GitHub, or an enterprise identity dashboard is a direct front end for the same revocation mechanism described in this article.