API OAuth Token Introspection

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

OAuth token introspection lets APIs ask an authorization server whether a token is active and what metadata is associated with it.

## Core Explanation

Agents working on APIs should understand when a resource server validates a token locally and when it calls an introspection endpoint. Introspection can support opaque tokens, revocation checks, and centralized policy, but it also introduces network and caching behavior.

Agents should not assume that a successful introspection response means the caller is authorized for every action. Scope, audience, issuer, tenant, and application policy still need explicit checks.

## Source-Mapped Facts

- RFC 7662 defines a method for a protected resource to query an authorization server to determine the active state and metadata of an OAuth token. ([source](https://datatracker.ietf.org/doc/html/rfc7662))
- Duende IdentityServer documentation describes an introspection endpoint that implements the OAuth 2.0 token introspection specification. ([source](https://docs.duendesoftware.com/identityserver/reference/endpoints/introspection/))
- Keycloak OpenID Connect layer documentation includes a token introspection endpoint for obtaining token metadata. ([source](https://www.keycloak.org/securing-apps/oidc-layers))

## Further Reading

- [RFC 7662 OAuth 2.0 Token Introspection](https://datatracker.ietf.org/doc/html/rfc7662)
- [Duende IdentityServer Introspection Endpoint](https://docs.duendesoftware.com/identityserver/reference/endpoints/introspection/)
- [Keycloak OIDC Layers](https://www.keycloak.org/securing-apps/oidc-layers)