# What is OAuth Token Introspection?

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

Explainer by Boston Identity, 2026-10-17. 6 min read. https://insights.bostonidentity.com/glossary/token-introspection

- What it is: protocol
- Defined by: IETF, RFC 7662 (Standards Track)
- Who it's for: Teams running APIs that accept OAuth tokens

## 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 [S1 §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 [S1 §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 [S1 §2]. The call works whether or not the token carries that information itself, so it can sit alongside self-contained tokens or replace them [S1 §1].

Think of it like this: A shop clerk handed a gift card can phone the issuer to ask whether the card is still good and what balance it has, instead of trusting what is printed on it. The comparison stops at caching: a clerk who remembers yesterday's answer may accept a card cancelled this morning.

Not the same as: 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 [S1 §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: How a protected resource asks the authorization server whether a token is active, in six steps.]

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 [S1 §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 [S1 §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 [S1 §2.1].
3. **The authorization server runs its checks.** Because the resource relies on its answer, the server must perform every check that applies [S1 §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 [S1 §4]. For an opaque token this can be a database lookup. For a structured token the server parses and validates it [S1 §4].
4. **The server answers active or not.** The reply is a JSON object whose only required member is active, true or false [S1 §2.2]. Optional members include scope, client_id, username, sub, aud, iss and exp [S1 §2.2]. The server may tell different resources different things, for example showing each one only the scopes that concern it [S1 §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 [S1 §2.3]. The server should not add anything else, including why the token is inactive [S1 §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 [S1 §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 [BI-FIND-2026-1251](https://insights.bostonidentity.com/ref/BI-FIND-2026-1251). 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 [BI-FIND-2026-1155](https://insights.bostonidentity.com/ref/BI-FIND-2026-1155). Karl McGuinness's design for agent missions has an enforcement point resolve a reference token against the mission state through token introspection [BI-FIND-2026-0205](https://insights.bostonidentity.com/ref/BI-FIND-2026-0205).

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 [BI-FIND-2026-0666](https://insights.bostonidentity.com/ref/BI-FIND-2026-0666). 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 [BI-FIND-2026-0540](https://insights.bostonidentity.com/ref/BI-FIND-2026-0540).

## Where does it fit?

- Compared with 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 [S1 §2.2].
- Compared with 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 [S1 App. A].
- Compared with 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 [BI-FIND-2026-1251](https://insights.bostonidentity.com/ref/BI-FIND-2026-1251).

## 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 [S1 §4]. PayPal's 300-second cache is that window in practice [BI-FIND-2026-0666](https://insights.bostonidentity.com/ref/BI-FIND-2026-0666).
- 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 [S1 §4].
- Each authorization server decides what active means and which checks apply, so active: true covers only the checks that server ran [S1 §2] [S1 §4]. If the server skips one, such as revocation or audience, the resource may make a wrong security decision based on the response [S1 §4].
- The endpoint must be protected by TLS. The server must support TLS 1.2, and the caller must check the server's certificate [S1 §2] [S1 §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 [S1 §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 [S1 §5].
- Bearer tokens travel in full. With a bearer token, the resource holds the token's whole secret when it calls the endpoint [S1 App. A].

## What should a security leader ask?

1. Which of our APIs accept a token on its signature and expiry alone, and which ask the issuer whether it is still active?
2. How long do our APIs cache an introspection answer, and how long could a revoked agent token keep working because of it?
3. Who can call our introspection endpoint, and is it authenticated and rate-limited against token scanning?
4. What does our introspection response reveal about users to each API that asks?

## Sources

- [S1] [OAuth 2.0 Token Introspection (RFC 7662)](https://www.rfc-editor.org/rfc/rfc7662.txt) (IETF, RFC 7662, Standards Track, October 2015)

## Evidence

- [BI-FIND-2026-1251](https://insights.bostonidentity.com/ref/BI-FIND-2026-1251): Chen 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. (from "A China Mobile draft would end an agent's token when its task ends, if a webhook says so")
- [BI-FIND-2026-1155](https://insights.bostonidentity.com/ref/BI-FIND-2026-1155): The 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. (from "In Huawei's reworked OAuth draft, evidence signed by the token's subject can narrow access but never widen it")
- [BI-FIND-2026-0205](https://insights.bostonidentity.com/ref/BI-FIND-2026-0205): The 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. (from "A user's approved request is not yet authority an agent can be held to, and most deployments skip that step")
- [BI-FIND-2026-0666](https://insights.bostonidentity.com/ref/BI-FIND-2026-0666): The 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". (from "PayPal moved MCP tool permission checks into the server, and prompt-injected agents stopped getting through")
- [BI-FIND-2026-0540](https://insights.bostonidentity.com/ref/BI-FIND-2026-0540): R3 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. (from "AAuth's R3 lets an agent ask for an API's named operations, and a person approve one exact call")

---

© 2026 Boston Identity LLC. All rights reserved. Published by Boston Identity LLC.
Quote up to 100 words with the credit "Boston Identity, IAM Insights" and a link to https://insights.bostonidentity.com/glossary/token-introspection. Claim numbers may be cited freely. Training, fine-tuning and text-and-data-mining use of this page is permitted.
Terms: https://insights.bostonidentity.com/terms · How to cite: https://insights.bostonidentity.com/cite
