Token introspection (RFC 7662)
The rule
POST as.oid4pay.com/oauth/introspect is available but NOT required by resource-server
validators. Most resource servers validate the JWT-AT locally per the JWT-AT claim set. Merchants running the @oid4pay/oid4ac-merchant SDK MAY introspect for instant-revocation checks. The AS advertises introspection_endpoint in metadata. Introspection auth is a bearer JWT-AT or the private_key_jwt of the requesting resource server.
When to introspect vs validate locally
| Use case | Local JWT verification | Introspect |
|---|---|---|
| Steady-state per-request | Yes (RFC 9068) | No (latency cost) |
| Token revocation check | No | Yes (returns active=false for revoked tokens) |
| Auditor / forensic | No | Yes (full claim disclosure) |
The OID4Pay merchant SDKs default to local JWT verification per request and introspect only on revocation-sensitive operations (e.g. opening a pre-authorisation that may persist past the AT's 5-minute TTL).
Wire shape
POST /oauth/introspect HTTP/1.1
Host: as.oid4pay.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <merchant JWT-AT>
token=<subject token to inspect>
&token_type_hint=access_token200 response
{
"active": true,
"iss": "https://as.oid4pay.com",
"sub": "principal_id_b64url",
"aud": "https://shop.alpacanica.com",
"client_id": "client_abc",
"scope": "oid4ac:payment",
"exp": 1747260600,
"iat": 1747260300,
"jti": "01HJ9XK0YN0K6V6S8Y8E5P5W6Y",
"cnf": { "jkt": "..." },
"mandate_id": "mandate_xyz",
"agent_client_id": "client_abc"
}Inactive response
{ "active": false }A revoked, expired, or unknown token returns active: false with no further claims. RFC 7662 §2.2 mandates this minimum-disclosure shape to defeat token-existence
probing.
Auth
The introspecting resource server authenticates either with:
- A DPoP-bound JWT-AT it holds for itself (the AS validates the resource server's own AT and uses its
client_idas the introspecting party). private_key_jwt(the AS validates the assertion against the resource server's registered JWKS).
Rate limits
The sandbox limits introspection to 120 calls per minute per client; the production AS scales linearly
with merchant fleet size. Heavy callers should cache active: true responses for the AT's
remaining TTL.