v1oauth context
Introspection
POST /v1/oauth/introspect — RFC 7662 token introspection, confidential clients only.
POST {issuer}/introspect answers "is this token valid right now". The answer comes from current server state, not from the token's own claims — a revoked session, or a token replaced by rotation, returns active: false.
Prerequisites
| Condition | Notes |
|---|---|
| Client authentication | The caller must authenticate as a client first |
| Client type | Confidential clients only; public clients are rejected |
| Caching | The response always carries no-store |
Request
| Parameter | Type | Required | Notes |
|---|---|---|---|
token | string | ✅ | Token to inspect |
token_type_hint | string | Optional | Lookup hint; does not change the result |
curl -X POST 'https://id.example.com/v1/oauth/introspect' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "token=$ACCESS_TOKEN"Response
{
"active": true,
"scope": "openid profile",
"client_id": "cli_...",
"sub": "usr_...",
"aud": "auth",
"exp": 1763112000,
"iat": 1763111100
}An invalid or revoked token returns only { "active": false }, with every other field omitted.
Never cache an introspection result
Introspection is a point-in-time judgement. Once cached, revocation becomes ineffective for the cache window — an attacker holding a revoked token still passes.
When to use it
| Situation | Recommendation |
|---|---|
| Resource server validating a token | Prefer local verification with public keys; it saves a round-trip |
| Needing to know whether a token was revoked | Use this endpoint, or rely on short lifetimes plus refresh |
| Public clients | Not available; verify with public keys |
Related
- Key distribution: Public keys
- Token fields: Tokens