Skip to content
IAM Insights

Explainers · Glossary

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
39By month of the source: 2025-12: 0, 2026-01: 0, 2026-02: 2, 2026-03: 4, 2026-04: 0, 2026-05: 1, 2026-06: 1, 2026-07: 3, 2026-08: 1, 2026-09: 7, 2026-10: 4, 2026-11: 00by month, last 12
01

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

02

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
  1. The client presents a token
  2. The resource proves who it is
  3. The authorization server runs its checks
  4. The server answers active or not
  5. An inactive token gets a bare false
  6. The resource decides, and may cache
Fig. 1

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 →

  1. 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

  2. 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

  3. 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

  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

  5. An inactive token gets a bare false

    An expired, revoked or unknown token, or one this resource may not ask about, gets active set to false, and the RFC counts that as a normal response rather than an error.§2.3 The server should not add anything else, including why the token is inactive.§2.2

  6. 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

03

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

04

Where does it fit?

Compared withHow OAuth Token Introspection differs
OAuth 2.0 Token RevocationRFC 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
DPoPRFC 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 RequestsIn 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
05

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
06

What should a security leader ask?

  1. 01

    Which of our APIs accept a token on its signature and expiry alone, and which ask the issuer whether it is still active?

  2. 02

    How long do our APIs cache an introspection answer, and how long could a revoked agent token keep working because of it?

  3. 03

    Who can call our introspection endpoint, and is it authenticated and rate-limited against token scanning?

  4. 04

    What does our introspection response reveal about users to each API that asks?

07

Sources

›Evidence: 5 claims from 5 briefings
  1. 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.
  2. 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.
  3. 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.
  4. 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".
  5. 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.

  1. 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

  2. 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

  3. 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.

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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

  7. MCP client setup moves from registration to metadata checks in a Spring walkthrough

    Video · · OWASP Foundation · Oct 24, 2026

  8. 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

  9. 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

  10. 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

  11. 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

  12. 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

  13. 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

  14. 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

  15. 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

  16. 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

  17. IPC passes a delegation chain between services; its signature proves only the last signer

    Draft · · IETF Datatracker · Ravi Kant Sharma, Ericsson · Jul 23, 2026

  18. 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

  19. 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

  20. 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

  21. 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

  22. 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

  23. 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

  24. One author's OpenID Connect for Agents proposal checks each delegation hop but makes the chain optional

    Paper · · arXiv · Subramanya Nagabhushanaradhya · Sep 30, 2025

  25. 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

  26. 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

  27. 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

  28. In May 2023, Parecki described OAuth 2.1 as consolidation and DPoP as token protection

    Video · · Identiverse - A CRA Resource · Jun 17, 2024

  29. 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

  30. DPoP token binding depends on checks at the resource server

    Article · · RFC Editor · Daniel Fett et al. · Sep 2023

  31. Rich Authorization Requests need API-specific permission rules

    Article · · RFC Editor · Torsten Lodderstedt et al. · May 1, 2023

  32. 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

  33. 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

  34. 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

  35. 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

  36. 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

  37. RFC 8485 makes assurance values meaningful only within a named trust framework

    Article · · RFC Editor · Justin Richer et al. · Oct 12, 2018

  38. 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

  39. 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.