A stolen OAuth token stays useful until a resource server refuses it, and most resource servers have no way of knowing it was revoked. Self-contained JWT access tokens are validated locally and remain valid until they expire, while opaque tokens need a call back to the authorisation server on every use. Two IETF standards connect the two halves: RFC 7009 lets a client or administrator revoke a token, and RFC 7662 lets a resource server ask whether a token is still active. This guide explains how both endpoints work, how to choose between opaque and JWT access tokens, how to cache introspection safely, and how to make revocation actually reach the APIs that matter. It is written for API owners, identity engineers and incident responders who need tokens to die when they say so.
Key takeaways
- Revocation only works where someone checks. RFC 7009 marks a token as revoked at the authorisation server; a resource server validating JWTs locally will keep accepting it until
exp. - Revoke the refresh token first. RFC 7009 says revoking a refresh token should also invalidate access tokens from the same grant, where the server supports access token revocation.
- Introspection is a privileged API. RFC 7662 requires callers to authenticate, and inactive tokens must return only
{"active": false}. - Caching is a deliberate trade-off. Every second an introspection result is cached is a second a revoked token still works; never cache beyond the token's
exp. - Short lifetimes plus targeted introspection beat both extremes. Use short-lived JWTs for volume, and introspect for high-risk operations or where instant revocation is required.
How the two endpoints work
| Aspect | Revocation (RFC 7009) | Introspection (RFC 7662) |
|---|---|---|
| Status | Proposed Standard, August 2013 | Proposed Standard, October 2015 |
| Caller | The client the token was issued to | A protected resource (resource server) or other authorised party |
| Request | HTTPS POST, form-encoded token, optional token_type_hint (access_token or refresh_token) | POST, form-encoded token, optional token_type_hint |
| Caller authentication | Client authentication as in RFC 6749; server checks the token belongs to that client | Required (client credentials or a bearer token), to prevent token scanning; 401 on bad credentials |
| Success response | HTTP 200 whether the token was revoked or already invalid | JSON with required active boolean and optional scope, client_id, username, token_type, exp, iat, nbf, sub, aud, iss, jti |
| Errors | unsupported_token_type; on 503 the client must assume the token still exists and may retry | Unknown, expired or revoked tokens are not errors: "active": false |
| Discovery metadata (RFC 8414) | revocation_endpoint | introspection_endpoint |
Two details matter in practice. First, RFC 7009 notes that different servers may learn of a revocation at different times, so a 200 response tells you the authorisation server has accepted it, not that every API has. Second, RFC 7662 says inactive responses should contain nothing beyond active: false, so the endpoint does not leak why a token failed. It also allows servers to reject GET requests so tokens do not end up in access logs.
Signed introspection responses
RFC 9701 (Proposed Standard, January 2025) lets a resource server request a signed JWT response by sending Accept: application/token-introspection+jwt. The RFC 7662 members are carried inside a token_introspection claim, the JWT typ is token-introspection+jwt, and the outer JWT should not include sub or exp so it cannot be misused as an access token. Use it where the resource server needs non-repudiable proof of what the authorisation server asserted, for example regulated identity data. Resource servers must check the typ of incoming JWT access tokens so an introspection response is never accepted as one.
Opaque or JWT access tokens
RFC 9068 profiles JWT access tokens: typ at+jwt, required claims iss, exp, aud, sub, client_id, iat and jti, and resource servers must reject any other typ and any alg of none. The profile itself says nothing about revocation: a JWT validated locally cannot know it was revoked unless the resource server also introspects or consults a revocation feed.
| Factor | Opaque token plus introspection | JWT access token (RFC 9068) | Hybrid |
|---|---|---|---|
| Revocation latency | Immediate (bounded by cache TTL) | Up to the token lifetime | Immediate for sensitive calls, lifetime for others |
| Authorisation server load | One call per request or per cache miss | None per request | Introspection only on high-risk paths |
| Availability coupling | APIs fail if introspection is down | APIs work offline from the AS | Partial |
| Privacy | Claims stay at the AS; client sees nothing | Claims readable by anyone holding the token unless encrypted | Mixed |
| Typical lifetime | Can be longer because it is checked | Keep short (minutes) | Short JWTs |
| Best for | High-value APIs, financial and admin operations, low-volume B2B | High-volume internal microservices, edge validation | Mixed estates, gateways |
Decision rule: if the business needs "revoke now, effective now" (fraud, admin APIs, incident containment), the resource server must introspect or receive revocation events. If minutes of residual validity are acceptable, short-lived JWTs with refresh token revocation are simpler and more resilient. See the JWT Security Guide and the Token Lifetime Policy Design Guide.
Small organisations: you rarely run your own authorisation server, so the choice is made by your identity provider and SaaS vendors. Ask each one how long access tokens live, whether revoking a user or app revokes refresh tokens immediately, and whether its APIs honour revocation before expiry. Large organisations: set a revocation latency target per API tier (for example under one minute for tier 1, under fifteen minutes for tier 3) and let teams choose introspection or short-lived JWTs to meet it.
Caching introspection safely
RFC 7662 is explicit that caching improves performance but risks accepting revoked tokens, and that a response with exp must not be cached past that time. Choose the cache TTL as a security parameter, not a performance one.
- Cache key: a hash of the token (for example SHA-256), never the raw token, so a memory dump or cache leak does not expose live credentials.
- TTL: the shorter of your revocation tolerance (for example 30 to 60 seconds for sensitive APIs) and the token's remaining
exp. - Negative caching: cache
active: falsebriefly to absorb replay storms, but do not let a negative result for one token affect another. - Per-risk TTL: zero TTL (always introspect) for privilege changes, payments and key management; longer for read-only, low-sensitivity reads.
- Fail closed: if introspection is unavailable and there is no valid cached result, reject the request for sensitive operations. Decide and document whether low-risk reads fail open.
- Purge on event: where the authorisation server can push revocation events (for example Shared Signals), evict the cache entry immediately. See the Shared Signals Framework Guide.
Making revocation propagate
Revocation is a chain: the trigger, the authorisation server, every token derived from the grant, and every resource server that caches or validates locally. Break any link and the token lives on.
| Trigger | What to revoke | How it reaches APIs |
|---|---|---|
| User signs out of a client | Refresh token for that client (RFC 7009), which should cascade to its access tokens | Introspecting APIs see active: false; JWT APIs wait for exp |
| Leaver or account disable | All refresh tokens and grants for the user across clients, including offline_access | Admin API of the AS plus session logout (see the OpenID Connect Logout and Session Management Guide) |
| Suspected token theft | The grant, all tokens for the client and user; consider all tokens for the client | Introspection, cache purge, temporary deny list of jti values at gateways |
| Third-party integration compromise | Every token issued to the integration's client ID; disable the client | Disable the client at the AS so new refreshes fail; introspection reports inactive |
| Signing key compromise | Rotate keys; all JWTs signed with the old key | Remove the key from the JWKS so local validation fails |
Check product behaviour: many authorisation servers do not support access token revocation for JWTs at all, and SaaS platforms differ on whether revoking a connected app removes refresh tokens immediately. Test it rather than assuming.
Enforcing revocation at gateways and resource servers
Most estates cannot introspect on every call, so the practical design combines several enforcement points. Pick deliberately per API rather than leaving it to each team.
API gateway introspection
A gateway or service mesh can introspect once at the edge and pass a verified, internal-only identity header or short-lived internal token to back-end services. This centralises caching and credentials, but the back ends must reject any request that did not come through the gateway, otherwise the check is bypassed by calling them directly.
Deny lists for JWTs
Where JWTs are validated locally, a small deny list of revoked jti values (or of subjects and client IDs under incident) distributed to resource servers gives near-immediate revocation without per-request calls. Entries only need to live until the matching token's exp, which keeps the list small when access tokens are short-lived. This is an implementation pattern, not a standard: document its distribution latency like any other cache.
Sender-constrained tokens reduce what revocation must do
RFC 9700 recommends sender-constrained access tokens using mTLS (RFC 8705) or DPoP (RFC 9449). A stolen sender-constrained token is useless without the client's private key, which shrinks the window in which revocation latency matters. It does not replace revocation when the client itself is compromised. See the DPoP Guide and the mTLS Guide.
Where identity fits
The tokens most often left unrevoked belong to non-human identities: integrations, connected apps, CI jobs and AI agents holding refresh tokens on behalf of users or service accounts. Give every such client an owner, record which grants it holds, and include "revoke all grants for this client ID" in integration offboarding. See the NHI Offboarding and Decommissioning Guide.
Implementation and rollout
- Inventory token types per API: record whether each resource server receives opaque tokens or JWTs, the access token lifetime, and whether it introspects. This is your revocation latency map.
- Publish the endpoints: expose
revocation_endpointandintrospection_endpointin authorisation server metadata, over TLS 1.2 or later, POST only. - Give each resource server its own introspection credential: register resource servers as clients with a distinct credential (preferably
private_key_jwtor mTLS) and restrict which audiences each may introspect, so one compromised API cannot probe tokens meant for others. - Wire revocation into clients: clients call RFC 7009 on sign-out and on uninstall, revoking the refresh token with
token_type_hint=refresh_token. - Wire revocation into operations: leaver workflows, incident playbooks and integration offboarding call the AS admin API to revoke grants per user and per client. See the OAuth Token Theft Incident Playbook.
- Pilot introspection on one sensitive API: start in shadow mode (introspect and log the result, keep accepting on local validation) to measure latency and the rate of tokens that local validation accepts but introspection rejects.
- Enforce: switch the pilot to reject on
active: false, set the cache TTL, and load test the authorisation server. - Roll back safely: keep a feature flag that returns to local validation with a reduced access token lifetime if the introspection endpoint becomes a bottleneck.
Detection and measurement
Log at the authorisation server: revocation requests (client, token type, result), introspection calls per caller, and introspection results by active value. Log at resource servers: requests rejected after introspection, and any request carrying a token whose jti was revoked. A spike in active: false from one API often means a stolen token is being replayed (ATT&CK T1550.001 Application Access Token, following T1528 Steal Application Access Token). A caller introspecting many unrelated tokens suggests token scanning.
- Revocation effectiveness time: time from revocation to first rejected request at each API, measured with a canary token monthly.
- Introspection coverage: share of high-risk APIs that introspect or consume revocation events, target 100%.
- Post-revocation acceptance: requests accepted with tokens already revoked, target zero for introspecting APIs.
- Introspection latency and availability: p95 latency and error rate, which decide whether teams keep using it.
- Leaver token residue: active grants for disabled users, target zero.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | IA-5 Authenticator Management; AC-2(3) Disable Accounts; AC-3 Access Enforcement; SI-4 System Monitoring | Token lifecycle, revocation on disable, enforcement at the resource, monitoring |
| NIST CSF 2.0 | PR.AA-01; PR.AA-05; DE.CM-03 | Credential management, enforced authorisation, monitoring |
| OWASP ASVS 5.0 | V10.3.1 audience; V10.3.5 replay prevention; V10.4.9 revocation of refresh and reference tokens | Resource server and authorisation server controls |
| ISO/IEC 27001:2022 Annex A | A.5.18 Access rights; A.8.5 Secure authentication | Revocation and secure token handling |
| MITRE ATT&CK | T1528; T1550.001 | Theft and reuse of application access tokens |
Common failure patterns
- Revoking without checking: the AS records the revocation, but every API validates long-lived JWTs locally, so the attacker keeps access for hours.
- Revoking the access token only: the refresh token survives and mints new access tokens. In the Salesloft Drift breach attackers held both access and refresh tokens for the Drift integration, and containment meant revoking all active access and refresh tokens for the application, not just the ones seen in use.
- Unauthenticated or shared introspection: one credential shared by every API, or no authentication at all, turns the endpoint into a token validity oracle.
- Caching for convenience: introspection results cached for an hour make revocation meaningless for that hour.
- Tokens in logs: GET-based introspection or debug logging writes live tokens into log stores. See the JWT and Session Tokens in Code and Logs Guide.
- Grants nobody revokes: integration tokens that are never revoked stay valid for years. In the Gainsight Salesforce breach the attacker held 285 refresh tokens, some created as far back as 2017, and Salesforce contained it by revoking all active access and refresh tokens tied to Gainsight-published apps.
Practitioner checklist
- Map every API's token format, lifetime and validation method.
- Require introspection or revocation events for admin, payment and data export APIs.
- Authenticate every introspection caller with its own credential and restrict audiences.
- Set introspection cache TTLs from revocation tolerance and never beyond
exp. - Revoke refresh tokens on sign-out, uninstall, leaver and incident, and confirm the cascade to access tokens.
- Keep JWT access token lifetimes short where introspection is not used.
- Accept POST only on both endpoints and keep tokens out of logs.
- Test revocation effectiveness monthly with a canary token per critical API.
Standards and references
- IETF: RFC 7662 OAuth 2.0 Token Introspection
- IETF: RFC 7009 OAuth 2.0 Token Revocation
- IETF: RFC 9701 JWT Response for OAuth Token Introspection
- IETF: RFC 9068 JWT Profile for OAuth 2.0 Access Tokens
- IETF: RFC 9700 Best Current Practice for OAuth 2.0 Security
- OpenID Foundation: OpenID Continuous Access Evaluation Profile 1.0
- OWASP: Application Security Verification Standard 5.0
Related NHI Mgmt Group resources: Token and Session Security Guide · OAuth Refresh Token Rotation and Expiry Guide · OAuth Token Theft Incident Playbook · JWT Security Guide · SaaS and OAuth App Governance Guide