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 Updated: 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?

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.

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.

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.

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.

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.

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.

Defense Pattern

Source Discipline

Claims about OAuth Token Introspection should identify the introspection endpoint, 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.

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