OAuth Token Introspection
RFC 7662 · RFC7662 · token introspection
By Boston Identity · Explained · 6 min read
The short answer
Token introspection lets an API ask the server that issued an OAuth token, at the moment of a request, whether that token is still active and what it allows. The issuer answers with a small JSON document.
- What it is
- A protocol
- Defined by
- IETF, RFC 7662 (Standards Track)
- Who it's for
- Teams running APIs that accept OAuth tokens
- In our briefings
- 390by month, last 12
What is OAuth Token Introspection?
OAuth is a standard for handing an app a token instead of a password. The app, called the client, treats that token as an opaque string. The API that receives it, called the protected resource or resource server, still has to decide whether to honour it. The token may carry metadata that matters for that decision: whether it is still valid, which scopes it was approved for, and who authorized it.§1 Before RFC 7662, the base OAuth 2.0 standard gave the API no way to ask for that metadata. Deployments filled the gap with structured tokens such as JSON Web Tokens (JWT), shared databases or private service buses.§1
RFC 7662, published by the Internet Engineering Task Force (IETF) in October 2015, defines one network call for this. The API posts the token to an introspection endpoint at the authorization server, the service that issued it. The server replies with whether the token is currently active and, optionally, its scopes, client, subject, audience and expiry.§2 The call works whether or not the token carries that information itself, so it can sit alongside self-contained tokens or replace them.§1
Introspection is not token revocation, which is a separate standard, RFC 7009. Introspection is how an API finds out, at call time, whether a token is still active, which includes whether it has been revoked.§2.2
How does OAuth Token Introspection work?
Three parties take part: a client that presents a token, the protected resource that receives it, and the authorization server that issued it and runs the introspection endpoint.
Figure steps
- The client presents a token
- The resource proves who it is
- The authorization server runs its checks
- The server answers active or not
- An inactive token gets a bare false
- The resource decides, and may cache
How a protected resource asks the authorization server whether a token is active, in six steps.
Drawn from RFC 7662, sections 2 and 4
Swipe for the full figure →
The client presents a token
A client calls the protected resource with an OAuth access token. To the client the token is opaque, and the resource needs to learn what stands behind it before it decides.§1
The resource proves who it is
The resource sends an HTTP POST with the token in a form field named token, plus an optional token_type_hint such as access_token.§2.1 It must authenticate itself on that call, for example with its own client credentials or a separate bearer token. The rule exists to stop attackers scanning for valid tokens.§2.1
The authorization server runs its checks
Because the resource relies on its answer, the server must perform every check that applies.§4 It checks expiry, whether the token's valid period has started, revocation, the signature if there is one, and whether the token may be used at the resource that is asking.§4 For an opaque token this can be a database lookup. For a structured token the server parses and validates it.§4
The server answers active or not
The reply is a JSON object whose only required member is active, true or false.§2.2 Optional members include scope, client_id, username, sub, aud, iss and exp.§2.2 The server may tell different resources different things, for example showing each one only the scopes that concern it.§2.2
The resource decides, and may cache
The resource makes its authorization decision from the answer. It may cache the response to cut load, at the cost of acting on older information. A cached response must not outlive the exp value it carries.§4
Why does OAuth Token Introspection matter now?
Several agent designs we have read ask the issuer about a token at the moment an API acts on it. A draft from Chen and Su would end an agent's token when its task ends. It says resource servers must check for revocation in real time, through a revocation feed or token introspection.1 Another draft notes that revoking a key leaves already-issued JWT access tokens unchanged. For prompt revocation, its authors say deployments should use short-lived tokens, introspection or both.2 Karl McGuinness's design for agent missions has an enforcement point resolve a reference token against the mission state through token introspection.3
The cost shows up in PayPal's report, whose only production numbers are a week of its token-introspection cache: 96.1% hits, 9.9 ms against 296 ms on a miss. That cache means a revoked token keeps working for up to its 300-second lifetime.4 R3, a scheme in which a resource names its own operations, avoids the call: it writes the granted operations into the access token and states that no token introspection is needed at enforcement time.5
Where does it fit?
| Compared with | How OAuth Token Introspection differs |
|---|---|
| OAuth 2.0 Token Revocation | RFC 7009, OAuth Token Revocation, is a separate standard. Introspection is how an API learns whether a token is still active when it is presented, which includes whether it has been revoked.§2.2 |
| DPoP | RFC 7662 does not settle proof-of-possession tokens. With those, the resource holds only a token identifier and a signed request, and could ask the introspection endpoint for the key; the RFC leaves the details to a later extension.App. A |
| Rich Authorization Requests | In Chen and Su's draft, a client adds a lifecycle_binding to its Rich Authorization Requests (RAR) request, and resource servers must then check for revocation in real time, through a revocation feed or token introspection.1 |
What goes wrong?
- Caching opens a window. A revoked token can keep working at a resource that relies on a cached answer. The RFC says designers must weigh this, and highly sensitive services can turn caching off entirely, at the cost of more traffic.§4 PayPal's 300-second cache is that window in practice.4
- An open endpoint invites token fishing. Left unprotected and un-throttled, it lets an attacker try many token values until one comes back active. The server must therefore authenticate callers and should authorize them specifically.§4
- Each authorization server decides what active means and which checks apply, so active: true covers only the checks that server ran.§2,§4 If the server skips one, such as revocation or audience, the resource may make a wrong security decision based on the response.§4
- The endpoint must be protected by TLS. The server must support TLS 1.2, and the caller must check the server's certificate.§2,§4
- Tokens can leak into logs. A server may refuse HTTP GET and require POST, so token values do not land in logs through query strings.§4
- Responses can expose people. User identifiers in a response are privacy-sensitive, and measures must be taken to keep them from unintended parties, for example by returning opaque identifiers that differ per resource.§5
- Bearer tokens travel in full. With a bearer token, the resource holds the token's whole secret when it calls the endpoint.App. A
What should a security leader ask?
- 01
Which of our APIs accept a token on its signature and expiry alone, and which ask the issuer whether it is still active?
- 02
How long do our APIs cache an introspection answer, and how long could a revoked agent token keep working because of it?
- 03
Who can call our introspection endpoint, and is it authenticated and rate-limited against token scanning?
- 04
What does our introspection response reveal about users to each API that asks?
Sources
- S1
OAuth 2.0 Token Introspection (RFC 7662)IETF · RFC 7662, Standards Track, October 2015
›Evidence: 5 claims from 5 briefings
- 1BI-FIND-2026-1251 · A China Mobile draft would end an agent's token when its task ends, if a webhook says soChen and Su's draft lets an agent's access token end when its task does, not only when it expires. The client adds a lifecycle_binding to its Rich Authorization Requests (RAR) request, naming a task id and the states that end the task. The one binding type the draft defines is a task-status webhook: the task provider reports those states to the authorization server, which MUST link the task to the token and, when the task ends, "MUST immediately revoke the associated token and propagate this revocation information." Resource servers SHOULD NOT rely solely on the token's expiry and MUST check for revocation in real time, through a revocation feed or token introspection. The authors call the scheme "entirely dependent" on that notice arriving and keep expiry as the fallback; the authorization server has to trust the task provider's webhook, and they say only that mutual TLS and request signing SHOULD protect it. We read the cost as falling on every API: a token carrying the binding can no longer be trusted on its signature and expiry alone, and if the webhook never fires, nothing ends it early.
- 2BI-FIND-2026-1155 · In Huawei's reworked OAuth draft, evidence signed by the token's subject can narrow access but never widen itThe key has to come from the authorization server's own records, and the draft closes the shortcuts around that. Before conveying a key, the server must authenticate the subject (or rely on a trusted provisioning process) and verify control of the private key unless such a process already has: "Merely receiving a public key is not proof of private-key control." It must not copy a key the client supplied in a request into subject_keys without establishing it through that same process, and a client's ordinary access or refresh token must not, by itself, be enough to create, replace or reactivate a key. The resource server must not accept a key from the client or from the evidence, must pick exactly one key by an integrity-protected key id or another unambiguous rule, and, when it introspects, must use that answer rather than merge it with the token's copy. Revoking a key leaves already-issued JWT access tokens unchanged; for prompt revocation the authors say deployments should use short-lived tokens, introspection or both.
- 3BI-FIND-2026-0205 · A user's approved request is not yet authority an agent can be held to, and most deployments skip that stepThe conversion step can be built from OAuth pieces that already exist. McGuinness's worked case, a CFO asking for a board packet, issues a narrow discovery envelope first, derives a fuller execution envelope from what discovery finds, and forces a callback for anything beyond it, with one mission state owner versioning the whole thing; a proposal reaches the authorization server through Pushed Authorization Requests (RFC 9126) so its content cannot be tampered with before approval, and an enforcement point resolves a reference token against the mission state through token introspection (RFC 7662). Widening authority is an approval event, not a local agent decision. A design on paper, from one author, and the first in this corpus to say what narrowing at each stage would actually look like.
- 4BI-FIND-2026-0666 · PayPal moved MCP tool permission checks into the server, and prompt-injected agents stopped getting throughThe production claim is thin and the limits are stated. PayPal says the extensions run on its internal agent platform across "dozens of authenticated MCP servers", with no counts of tools, agents or requests, and the only production numbers are a week's token-introspection cache (96.1% hits, 9.9 ms against 296 ms on a miss). That cache means a revoked token keeps working for up to its 300-second lifetime. Tools nobody annotated default to open, OAuth token exchange is left for future work, so no delegation chain crosses servers, and the code is promised for a repository whose link is "to be added".
- 5BI-FIND-2026-0540 · AAuth's R3 lets an agent ask for an API's named operations, and a person approve one exact callR3 replaces scope strings with operations the resource itself names. A resource lists the vocabularies it speaks (MCP, OpenAPI, AsyncAPI, OData and three more); the agent requests operations by those names; the resource answers with a JSON document describing them, including a plain-language summary, what data is touched and what cannot be undone, identified by the SHA-256 of its exact bytes. The person's server shows that description for consent, the issuer writes the granted operations and the hash into the access token, and the resource enforces from the token alone: "No token introspection or R3 document fetch is needed at enforcement time." The agent sees only the hash and its own grant, never the document.
›In our briefings
The claim each of the newest briefings on OAuth Token Introspection would have you leave with.
Token Status List puts the status of many tokens in a signed, compressed bit array per list, which the authors size for up to millions of tokens, and an issuer may run several lists. Each token carries an index and the list's URI. A verifier fetches the list, validates it and reads the token's 1, 2, 4 or 8 bits for VALID, INVALID, SUSPENDED or an application-specific value. Because many tokens share one list, the issuer does not learn which token a verifier is asking about, which the authors call herd privacy. With OAuth introspection, by contrast, the verifier contacts the issuer about each token. The draft warns that an issuer could defeat this with a unique list or list URI per token, which relying parties that verify many tokens can spot by comparing the number and size of lists with the tokens they see. The uri and index pair is unique to each token, so the draft also warns that a relying party may track one token's status over time and that colluding parties may link two transactions involving the same token; it recommends batches of one-time-use tokens. A revocation reaches a verifier when it next fetches the list, and the issuer can signal how long a copy may be cached through the list's exp and ttl.
OAuth's token revocation list nears RFC, and a shared list hides which token is checkedBI-FIND-2026-0632
Richer's draft would add another way to bind an OAuth access token to a client's key, beside DPoP and mutual TLS. Its introduction says the work "complements and builds on experience with" those two, and the draft names no gap in either; when to use which is left to an editor's note, and the security and privacy sections are marked TBD. The authors argued for it on the mailing list during the adoption call that closed on 5 October. Paul Bastian cited DPoP shortcomings he had co-presented at the OAuth Security Workshop and TLS that ends at DDoS-protection or corporate proxies. Richer said HTTP Message Signatures (RFC 9421) is now published and widely deployed. Neil Madden, replying to Bastian's workshop slides, suggested summarising some of their rationale in the draft's introduction. Nine people supported adoption, five of them authors, and four objected: Dick Hardt said the group had already solved key binding with DPoP, and Michael Jones and Brian Campbell, two of DPoP's co-authors, said another method would hurt interoperability. The chairs had posted no decision by 12 October.
The OAuth working group split over a token-binding draft that never says what DPoP lacksBI-FIND-2026-0862
A person's approved request is not, by itself, authority an agent can be held to, McGuinness argues, and relatively few deployments perform the step that would make it one. That step converts approved intent into a bounded authority artifact an enforcement point can evaluate. By his account, many systems instead fall into one of five patterns: scope enumeration, app-local mapping, LLM-generated requests, broad standing authority with prompt discipline, or a formal policy language. He says the most common land in the third or fourth, and that where nothing makes the conversion, the agent's own judgment becomes the effective policy engine. This is one author's argument, but two production designs we have read fit it. Uber's agent tokens carry the full chain of who asked through every hop, and Sierra's gateway runs interactive agent work as the user, with that person's permissions. In our reading, neither records what the person approved.
A user's approved request is not yet authority an agent can be held to, and most deployments skip that stepBI-FIND-2026-0202
›Cited in 39 briefings
Every briefing that discusses this term, newest first.
- OAuth's token revocation list nears RFC, and a shared list hides which token is checked
Draft · · IETF Datatracker · Tobias Looker et al. · Aug 13, 2026
- The OAuth working group split over a token-binding draft that never says what DPoP lacks
Draft · · IETF Datatracker · Justin Richer et al. · Jul 28, 2026
- A user's approved request is not yet authority an agent can be held to, and most deployments skip that step
Article · · Control Plane by Karl McGuinness · Karl McGuinness · Mar 17, 2026
- An OAuth client gets to name who vouches for it, and removing one waits on server caches
Draft · · IETF Datatracker · Karl McGuinness · Sep 28, 2026
- WIMSE's agent draft adds how an agent's access ends and where policy engines fit, without a new requirement
Draft · · IETF WIMSE Working Group · Pieter Kasselman et al. · Sep 15, 2026
- OAuth tokens prove an agent's rights, not a person's consent; revision 05 adds a day-long grant with spend caps
Draft · · IETF Datatracker · Meiling Chen et al. · Oct 27, 2026
- MCP client setup moves from registration to metadata checks in a Spring walkthrough
Video · · OWASP Foundation · Oct 24, 2026
- ChainIT's design has the payment rail rebuild each payment's hash before money moves; the paper reports no test
Paper · · arXiv · Jeremy Blackburn et al. · Oct 16, 2026
- An OAuth profile for AI agents makes every hand-off cut privileges, but a shorter expiry alone counts as a cut
Draft · · IETF Datatracker · Angel Cruz · Feb 7, 2026
- In Huawei's reworked OAuth draft, evidence signed by the token's subject can narrow access but never widen it
Draft · · IETF Datatracker · Cheng-Kang Chu et al. · Sep 1, 2026
- TPX replaces an app's embedded AI provider key with a capped, metered grant the user approves at their provider
Article · · tokenpony.dev · Alex Polvi · Jul 20, 2026
- Three vendors now route MCP tool calls through an identity check, and only Cloudflare's is generally available
Release tracker · · 11 vendors' release notes · Sep 2026
- NIST and CISA advise one-hour tokens, 90-day keys and hardware key storage; AI agents get one paragraph
Article · · NIST (CSRC) · Ryan Galluzzo et al. · Sep 15, 2026
- PayPal moved MCP tool permission checks into the server, and prompt-injected agents stopped getting through
Paper · · arXiv · Huan Li et al. · Sep 18, 2026
- AAuth's R3 lets an agent ask for an API's named operations, and a person approve one exact call
Draft · · IETF Datatracker · Dick Hardt · Sep 28, 2026
- A draft token hides some claims, works with old servers unchanged, and leaves agent delegation claims visible
Draft · · IETF Datatracker · Su-hyeon Forten Lee · Oct 3, 2026
- IPC passes a delegation chain between services; its signature proves only the last signer
Draft · · IETF Datatracker · Ravi Kant Sharma, Ericsson · Jul 23, 2026
- A June OAuth draft logs each hand-off between AI agents, but the per-hop limits the act claim lacks are optional
Draft · · IETF Datatracker · Dapeng Liu et al. · Jun 8, 2026
- A preprint cuts off every sub-agent within about 40 seconds of its parent stopping, with no revocation server
Paper · · arXiv · Saurabh Deochake, SentinelOne · May 20, 2026
- OpenID agent-claims draft adds a provider-set user, application or agent label; scores stay each provider's own
Draft · · IETF Datatracker · Raza Sharif, CyberSecAI · Mar 26, 2026
- A cross-domain agent trust draft requires the call chain, then leaves its format to a version that never came
Draft · · IETF Datatracker · Daniel King et al. · Mar 15, 2026
- OAuth 2.1's October draft bans plain PKCE and adds browser-app rules; 2.1-only clients can fail on older servers
Draft · · IETF Datatracker · Dick Hardt et al. · Mar 2, 2026
- A China Mobile draft would end an agent's token when its task ends, if a webhook says so
Draft · · IETF Datatracker · Meiling Chen et al. · Feb 4, 2026
- One author's OpenID Connect for Agents proposal checks each delegation hop but makes the chain optional
Paper · · arXiv · Subramanya Nagabhushanaradhya · Sep 30, 2025
- Auth0's DPoP explainer leaves out the access-token hash that RFC 9449 requires on every API call
Article · · Auth0 Blog · Andrea Chiarelli · Aug 25, 2025
- A rogue OAuth server can collect a client's signed assertion and replay it at an honest server the client also uses
Article · · IACR Cryptology ePrint Archive · Pedram Hosseyni et al. · Apr 7, 2025
- In GNAP (RFC 9635), a client is known by its key, and tokens stay key-bound unless the server flags them bearer
Article · · RFC Editor · Justin Richer et al. · Oct 1, 2024
- In May 2023, Parecki described OAuth 2.1 as consolidation and DPoP as token protection
Video · · Identiverse - A CRA Resource · Jun 17, 2024
- RFC 9470 lets an API demand a fresher or stronger sign-in, with no shared scale for 'stronger'
Article · · RFC Editor · Vittorio Bertocci et al. · Sep 8, 2023
- DPoP token binding depends on checks at the resource server
Article · · RFC Editor · Daniel Fett et al. · Sep 2023
- Rich Authorization Requests need API-specific permission rules
Article · · RFC Editor · Torsten Lodderstedt et al. · May 1, 2023
- RFC 9068 makes resource servers check a JWT access token's type and audience, and warns a client could pose as a user
Article · · RFC Editor · Vittorio Bertocci, Okta · Oct 1, 2021
- RFC 8705 lets OAuth bind tokens to a client certificate, and leaves the proxy in front of the API to the deployer
Article · · RFC Editor · Brian Campbell et al. · Feb 28, 2020
- OAuth's resource indicators RFC says servers should bind tokens to a resource, but requires it of neither side
Article · · RFC Editor · Brian Campbell et al. · Feb 1, 2020
- The token exchange RFC that agent designs cite says its record of earlier actors is not for access decisions
Article · · IETF Datatracker · Michael B. Jones et al. · Jan 1, 2020
- In draft FAPI, token binding did not make phished tokens useless: the attacker had the bound client spend them
Paper · · arXiv · Daniel Fett et al. · Jan 31, 2019
- RFC 8485 makes assurance values meaningful only within a named trust framework
Article · · RFC Editor · Justin Richer et al. · Oct 12, 2018
- RFC 8414 tells an OAuth client to discard server metadata whose issuer differs from the URL it started from
Article · · RFC Editor · Michael B. Jones et al. · Jun 1, 2018
- Trying to prove OAuth 2.0 secure, a 2016 Trier paper found four attacks, the IdP mix-up among them
Paper · · arXiv · Daniel Fett et al. · Jan 6, 2016
Related terms
What appears alongside OAuth Token Introspection in the same briefings.
DPoPOAuth 2.0 Token RevocationRich Authorization RequestsOAuth 2.0 Authorization Server MetadataPushed Authorization RequestsOAuth 2.0 Security Best Current PracticeResource Indicators for OAuth 2.0mTLS
Was this explainer useful?
Share this explainer
Pass it on. Every claim has a permanent number, so what you share today still points at the same words next year.