RFC 7662 — Token Introspection

Specification: RFC 7662

Token Introspection lets a resource server ask the authorization server about the state and metadata of an access or refresh token.

Status

Implemented. Checked claims: 24 of 27.

Endpoint

• POST /introspect endpoint (Section 2)
• application/x-www-form-urlencoded request body

Token types

• Access token introspection (JWT)
• Refresh token introspection (opaque)
• Token type detected by format
• token_type_hint is accepted and ignored, which the RFC permits

Client authentication

• Client authentication required (Section 2.1); failure returns 401 invalid_client
• client_secret_basic and client_secret_post
• private_key_jwt (RFC 7523)
• tls_client_auth and self_signed_tls_client_auth (RFC 8705)
• A caller presenting nothing but a client_id is refused, because a public client’s id is not a secret

Authorization of the caller

• A caller may introspect an access token only when its audience includes a resource the caller can access; otherwise the answer is {"active": false}
• A refresh token issued to another client is refused with invalid_client

Response fields (Section 2.2)

• active
• scope — space-delimited scopes
• client_id
• token_type — DPoP for a DPoP-bound token, Bearer otherwise
• exp and iat
• sub, aud and iss
• jti — for access tokens
• cnf — the token’s whole confirmation, with jkt for a DPoP-bound and x5t#S256 for a certificate-bound token (RFC 9449, RFC 8705)
• authorization_details when the token carries them (RFC 9396)
• username — never returned
• nbf — returned only for a token that carries one; issued tokens do not

Response headers and states

• Cache-Control: no-store and Pragma: no-cache on responses
• {"active": false} for expired, malformed, unknown or foreign tokens
• active: false for a revoked access token — not reported by auth; a revoked access token introspects as active until it expires (see RFC 7009)

Notes

• The revocation check for access tokens lives in edge, which refuses a revoked token before its expiry.

Where to look

The OpenAPI reference has the introspection specification.