Reference

POST /partner/v1/oauth/introspect

The OAuth 2.0 token-introspection endpoint. Check whether an access token is active and read its scopes, expiry and subject without decoding the JWT yourself.

2 min read

POSTHTTP method

OAuthAuth

partnerRing

Endpoint

Method	`POST`
Path	`/partner/v1/oauth/introspect`
Ring	partner (OAuth introspection)

Parameters

Form-encoded body with the token to introspect (and client authentication).

Response

A JSON object per RFC 7662: active (boolean) and, when active, the token's scope, exp, client_id and related claims. Use introspection when you want the authorization server to be the source of truth for validity — for example to honour a revocation immediately — rather than trusting a still-unexpired JWT you decoded locally.

Errors

An inactive or unknown token returns active: false (not an error). Client-authentication failures return an OAuth error. Rate-limited like the rest of the token plane.

Frequently asked questions

When should I introspect instead of verifying the JWT?

Introspect when you need the server to be authoritative about validity — for instance to respect a revocation before the JWT would naturally expire. Local JWKS verification is faster but cannot see a revocation mid-lifetime.

Is an inactive token an error?

No. Introspecting an expired, revoked or unknown token returns active:false with a 200 — that is the expected answer, not a failure. Branch on the active flag.