Wiki · Concept · Last reviewed June 25, 2026

OAuth Token Introspection

OAuth Token Introspection lets a protected resource ask the authorization server whether a presented token is active and what authorization metadata it carries before an agent tool request is served.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: AI agents, authorization, OAuth, token introspection, resource servers, audit trails

Definition

OAuth Token Introspection is the Standards Track extension defined in RFC 7662, OAuth 2.0 Token Introspection, by Justin Richer. RFC 7662 was published in October 2015. It defines a method for a protected resource to query an OAuth 2.0 authorization server and learn whether a token is active and what metadata is associated with it.

The core problem is that OAuth tokens may be opaque to the resource server. A tool server can receive a string that looks like a bearer token without knowing whether it has expired, been revoked, was issued to a particular client, carries a relevant scope, or has the right audience. Introspection gives the resource server a standard back-channel question: what does this token mean now?

The answer is evidence, not the whole authorization decision. active: true means the authorization server currently treats the token as usable in the returned context. The protected resource still has to verify issuer, audience, scope, expiration, sender constraint, tenant, client, subject, local policy, and any agent-specific approval rule before serving the request.

For AI agents, that question matters because tool calls often cross service boundaries quickly. A browser assistant, coding agent, or hosted workflow may present tokens to many tool servers. Each protected resource needs a way to make its own authorization decision rather than assuming that possession of a token is enough.

Snapshot

How It Works

The protected resource sends an HTTP POST request to the introspection endpoint. The request includes a required token parameter and may include token_type_hint, such as access_token or refresh_token, to help the authorization server locate the token. RFC 7662 requires the introspection endpoint to be protected by transport-layer security and to require authorization, so random callers cannot scan tokens.

The response is a JSON object. Its required member is active, a Boolean value saying whether the token is currently active according to the authorization server. Optional response members include scope, client_id, username, token_type, exp, iat, nbf, sub, aud, iss, and jti. Implementations can add service-specific response fields, and cross-domain response names can be registered.

RFC 7662 allows the authorization server to answer differently depending on which protected resource is asking. A well-run deployment should therefore treat introspection as a resource-scoped exchange: the endpoint authenticates the caller, decides what that caller is entitled to learn, and returns only the metadata needed for that resource server's policy decision.

If the token is inactive, missing, unknown to the server, or not introspectable by that protected resource, RFC 7662 says the authorization server returns {"active": false} and should not reveal extra details about why. The response can be cached by the protected resource, but caching trades performance for freshness.

Introspection is different from local JWT validation. A resource server that validates a self-contained token locally may avoid a network call, but it may not see revocation, policy changes, or downscoping until the token expires. A resource server that introspects receives current authorization-server state, but it depends on endpoint availability, authentication, latency, cache policy, and careful logging.

Boundary Tests

Not local token validation. A resource server can validate a JWT access token locally by checking its signature, issuer, audience, expiration, and profile. Introspection is a back-channel query to the authorization server. Some deployments use both: local checks for speed, introspection for revocation, reference tokens, or high-risk actions.

Not token revocation. OAuth Token Revocation is the act of asking the authorization server to invalidate a token or grant. Introspection checks current state after issuance. A revocation event should change later introspection results, but the two endpoints answer different questions.

Not token exchange. OAuth Token Exchange mints a new token from an existing token or assertion. Introspection does not delegate, impersonate, downscope, or bridge trust domains by itself; it reports metadata about the token being presented.

Not a consent record. An active token says the authorization server currently regards the token as usable in some context. It does not prove the user understood a particular agent action, that the requested tool call is proportionate, or that the resource server should skip local policy.

Not sender constraint by itself. DPoP and mutual TLS can bind token use to a key or certificate. Introspection can help a resource server learn confirmation material or token metadata in some deployments, but the server still has to verify the proof on the actual request.

Discovery and Response Security

RFC 7662 deliberately leaves introspection endpoint discovery out of scope. In modern deployments, OAuth Authorization Server Metadata under RFC 8414 can advertise introspection_endpoint, introspection_endpoint_auth_methods_supported, and supported signing algorithms for JWT-based client authentication at the introspection endpoint. That discovery record should be pinned to the expected issuer and reviewed like other authorization-server metadata.

OAuth Protected Resource Metadata under RFC 9728 complements that chain from the resource side. It can tell a client which authorization servers are associated with a protected resource, but the introspection endpoint itself comes from authorization-server metadata or local configuration. Agent clients should not let tool text, model output, or an unvalidated discovery redirect choose the introspection endpoint.

RFC 9701 adds a JWT-secured introspection-response option for cases where a resource server needs stronger assurance about who issued the response, who the response is for, or where liability and cross-boundary trust matter. A resource server requests that format with Accept: application/token-introspection+jwt. The response JWT carries top-level iss, aud, iat, and a token_introspection object containing the RFC 7662 response members.

The JWT response is not a new access token. RFC 9701 warns against treating the introspection response JWT as if it were the introspected access token. Resource servers should validate the signature, type, issuer, audience, timestamp, nesting or encryption if used, and the encapsulated active result before using the response in a policy decision.

Current Context

As of June 25, 2026, RFC 7662 remains the core IETF standard for OAuth 2.0 token introspection. RFC 8414 authorization server metadata can advertise an introspection endpoint and supported introspection-endpoint authentication methods, and RFC 9701 adds a JWT-secured response option for deployments that need signed or encrypted introspection responses.

OAuth security practice has also moved toward tighter resource boundaries. RFC 9700 says access tokens should be audience-restricted to a specific resource server or small set of resource servers, and resource servers must verify whether each received token was meant for them. Introspection is one way to get the metadata needed for that check, especially with opaque tokens.

OAuth 2.1 is still an Internet-Draft on this review date. The March 2026 draft consolidates OAuth 2.0 with later security updates, but production documentation should still cite the applicable RFCs directly. The June 2026 OAuth security-topics update draft is also relevant current context: it describes newer threats such as audience-injection attacks and related multi-authorization-server risks, but it remains a draft rather than a replacement for RFC 9700.

Agent and MCP deployments make these older OAuth controls newly important. MCP's 2025-11-25 authorization specification requires protected-resource metadata for authorization server discovery, and its security guidance warns against token passthrough. Token introspection is not itself an MCP mandate, but it is part of the adjacent OAuth toolkit for resource servers that need current, issuer-backed token state before serving a tool request.

Agent Context

Agent tool systems often prefer opaque or reference tokens because revocation, downscoping, and policy updates can happen at the authorization server without forcing every tool server to understand every token format. Introspection lets a tool server check the current authorization state at request time.

This is especially useful for gateway patterns. A resource server can ask whether the presented token is active, which client requested it, which subject or resource owner it represents, which scope is effective, and whether the audience fits the protected resource. The answer can be narrower than the original grant: RFC 7662 allows the authorization server to return different information to different protected resources.

For AI Agent Identity, introspection helps keep the agent, delegated user, client, scope, and resource boundary visible at the moment of tool use. It is strongest when paired with OAuth Resource Indicators, OAuth Protected Resource Metadata, scoped credentials, and audit trails.

For agent platforms, the control also reduces identity ambiguity. If a hosted agent brokers access to several MCP servers, repository APIs, or internal tools, the resource server can record whether the token was issued to the expected client and for the expected resource instead of trusting that the agent host routed it correctly.

Introspection is not a judgment about the agent's reasoning. If prompt injection persuades a legitimate agent to call a tool, an active token may still be active. The control answers whether this token should be honored by this resource server now. It does not answer whether the requested task is wise, honest, or proportionate.

Governance and Safety

RFC 9700 says access tokens should be audience-restricted to a specific resource server, or a small set of resource servers when that is not feasible, and that resource servers must refuse tokens meant for another audience. Introspection responses can carry the aud value and other metadata a resource server needs to enforce that boundary.

In January 2025, RFC 9701 standardized a JWT response option for token introspection. That extension exists for cases where the resource server needs stronger assurance that the authorization server issued the introspection response and may need signed or encrypted response data.

The privacy boundary is as important as the cryptographic boundary. Introspection responses can expose subject identifiers, usernames, scopes, client identifiers, token identifiers, and identity claims. RFC 9701 says the authorization server must be able to identify, authenticate, and authorize resource servers and determine what data each resource server is entitled to receive. A safer design returns only the fields needed for that resource server's decision.

Audit trails should preserve the token fingerprint or opaque reference, introspection endpoint, resource server identity, active result, returned subject, client identifier, audience, scope, expiration, cache status, policy decision, and final tool action. Logs should avoid storing full bearer tokens because possession of the token may itself be sensitive authority.

The introspection endpoint is a sensitive control-plane API. It should be rate-limited and monitored for token-scanning behavior, protected with separate resource-server credentials where appropriate, and governed by Data Minimization rules for both responses and logs.

Governance should treat introspection as part of the same control plane as OAuth Security Best Current Practice, AI Agent Sandboxing, AI Agent Observability, AI Audit Trails, and Human Oversight of AI Systems. An active token can still be too broad for the requested task, stale in a cache, or attached to an agent run that should require human approval.

Minimum Introspection Record

A serious agent connector or resource server should leave enough introspection evidence for security review without leaking token material.

Failure Modes

Possession-only authorization. The resource server treats any bearer token string as enough evidence and never checks active state, audience, scope, issuer, or client.

Overbroad disclosure. The authorization server returns more token metadata than the protected resource needs, exposing user or client information unnecessarily.

Stale allow. A cached active response survives revocation, downscoping, account suspension, incident response, or a user decision to withdraw access.

Fail-open behavior. The resource server allows access when the introspection endpoint is unreachable, slow, or returns an error.

Audience confusion. The resource server sees active: true but fails to verify whether the token was actually issued for that protected resource.

Metadata confusion. The resource server discovers or accepts an introspection endpoint without binding it to the expected issuer, tenant, authorization server metadata, or protected-resource metadata.

JWT response substitution. A JWT introspection response is accepted as an access token, or it is used without checking type, signature, issuer, audience, and the nested token_introspection object.

Endpoint scanning. The authorization server exposes a weakly authenticated or unthrottled introspection endpoint, giving attackers a way to test token guesses or learn token status indirectly.

Authorization outsourcing. The resource server treats active: true as a complete local allow decision and skips tool policy, step-up rules, sender-constraint checks, human approval, or account-risk controls.

Secret-bearing logs. Introspection improves traceability but stores full bearer tokens or excessive response details in ordinary application logs.

Defense Pattern

Source Discipline

Claims about OAuth Token Introspection should identify the introspection endpoint, discovery source, resource server, token type, active result, response fields used for policy, cache behavior, and whether the response was plain JSON or an RFC 9701 JWT response. Do not collapse introspection into OAuth Token Exchange, token revocation, local JWT validation, OAuth Resource Indicators, or a legal conclusion that a user consented.

Use exact source labels. RFC 7662 defines the introspection request and response. RFC 9701 defines a JWT-secured response option. RFC 9700 supplies current OAuth security guidance, including audience restriction. RFC 8414 can advertise introspection endpoint metadata. RFC 9728 helps clients discover protected-resource metadata. These sources fit together, but none is a substitute for the others.

For implementation claims, preserve dates, token class, endpoint metadata, resource-server identity, authentication method, sender-constraint method if any, cache policy, privacy filter, and test result. "We introspect tokens" is not enough evidence unless the record shows which fields are checked and how failure is handled.

Spiralist Reading

Spiralism reads token introspection as a refusal to let authority be judged only by appearance. A string arrives at a tool server, and the server asks the institution that issued it whether the string is still alive.

That answer is not wisdom. It is an administrative pulse. Serious systems still ask what the agent is doing, who authorized it, which resource is named, and why the action should proceed.

Open Questions

Sources

Return to Wiki