Join our Newsletter — 33% off our NHI Course
Home› Guides› OAuth Token Introspection and Revocation Guide: Checking and…
Guide Authentication

OAuth Token Introspection and Revocation Guide: Checking and Killing Tokens in Real Time

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

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

AspectRevocation (RFC 7009)Introspection (RFC 7662)
StatusProposed Standard, August 2013Proposed Standard, October 2015
CallerThe client the token was issued toA protected resource (resource server) or other authorised party
RequestHTTPS POST, form-encoded token, optional token_type_hint (access_token or refresh_token)POST, form-encoded token, optional token_type_hint
Caller authenticationClient authentication as in RFC 6749; server checks the token belongs to that clientRequired (client credentials or a bearer token), to prevent token scanning; 401 on bad credentials
Success responseHTTP 200 whether the token was revoked or already invalidJSON with required active boolean and optional scope, client_id, username, token_type, exp, iat, nbf, sub, aud, iss, jti
Errorsunsupported_token_type; on 503 the client must assume the token still exists and may retryUnknown, expired or revoked tokens are not errors: "active": false
Discovery metadata (RFC 8414)revocation_endpointintrospection_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.

FactorOpaque token plus introspectionJWT access token (RFC 9068)Hybrid
Revocation latencyImmediate (bounded by cache TTL)Up to the token lifetimeImmediate for sensitive calls, lifetime for others
Authorisation server loadOne call per request or per cache missNone per requestIntrospection only on high-risk paths
Availability couplingAPIs fail if introspection is downAPIs work offline from the ASPartial
PrivacyClaims stay at the AS; client sees nothingClaims readable by anyone holding the token unless encryptedMixed
Typical lifetimeCan be longer because it is checkedKeep short (minutes)Short JWTs
Best forHigh-value APIs, financial and admin operations, low-volume B2BHigh-volume internal microservices, edge validationMixed 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: false briefly 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.

TriggerWhat to revokeHow it reaches APIs
User signs out of a clientRefresh token for that client (RFC 7009), which should cascade to its access tokensIntrospecting APIs see active: false; JWT APIs wait for exp
Leaver or account disableAll refresh tokens and grants for the user across clients, including offline_accessAdmin API of the AS plus session logout (see the OpenID Connect Logout and Session Management Guide)
Suspected token theftThe grant, all tokens for the client and user; consider all tokens for the clientIntrospection, cache purge, temporary deny list of jti values at gateways
Third-party integration compromiseEvery token issued to the integration's client ID; disable the clientDisable the client at the AS so new refreshes fail; introspection reports inactive
Signing key compromiseRotate keys; all JWTs signed with the old keyRemove 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

  1. 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.
  2. Publish the endpoints: expose revocation_endpoint and introspection_endpoint in authorisation server metadata, over TLS 1.2 or later, POST only.
  3. Give each resource server its own introspection credential: register resource servers as clients with a distinct credential (preferably private_key_jwt or mTLS) and restrict which audiences each may introspect, so one compromised API cannot probe tokens meant for others.
  4. Wire revocation into clients: clients call RFC 7009 on sign-out and on uninstall, revoking the refresh token with token_type_hint=refresh_token.
  5. 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.
  6. 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.
  7. Enforce: switch the pilot to reject on active: false, set the cache TTL, and load test the authorisation server.
  8. 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

FrameworkReferenceRelevance
NIST SP 800-53 Rev. 5IA-5 Authenticator Management; AC-2(3) Disable Accounts; AC-3 Access Enforcement; SI-4 System MonitoringToken lifecycle, revocation on disable, enforcement at the resource, monitoring
NIST CSF 2.0PR.AA-01; PR.AA-05; DE.CM-03Credential management, enforced authorisation, monitoring
OWASP ASVS 5.0V10.3.1 audience; V10.3.5 replay prevention; V10.4.9 revocation of refresh and reference tokensResource server and authorisation server controls
ISO/IEC 27001:2022 Annex AA.5.18 Access rights; A.8.5 Secure authenticationRevocation and secure token handling
MITRE ATT&CKT1528; T1550.001Theft 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.