Skip to main content

Introspection & Revocation

Token introspection (RFC 7662)​

The introspection endpoint lets a resource server verify whether a token is valid without needing the signing key.

POST /oauth2/introspect

Authentication​

The introspection endpoint requires one of two forms of authentication per RFC 7662 Section 2.1:

  1. Client authentication — using HTTP Basic auth (client_secret_basic) or form-encoded credentials (client_secret_post). A client can only introspect tokens that were issued to itself.
  2. Admin bearer token — using Authorization: Bearer $ADMIN_TOKEN. Admin users can introspect any token regardless of which client it was issued to.

Request with client authentication (Basic auth):

curl -X POST https://auth.example.com/oauth2/introspect \
  -u "my-client-id:my-client-secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Request with admin bearer token:

curl -X POST https://auth.example.com/oauth2/introspect \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Active token response:

{
  "active": true,
  "sub": "user-uuid",
  "exp": 1700000000,
  "iat": 1699999100,
  "iss": "https://auth.example.com/oauth2",
  "aud": "my-client-id"
}

Inactive/expired token response:

{
  "active": false
}

When a client introspects a token that belongs to a different client, the endpoint returns {"active": false} rather than an error, to avoid leaking information about token existence (per RFC 7662 Section 2.2).

Token revocation (RFC 7009)​

The revocation endpoint invalidates a token immediately.

POST /oauth2/revoke

Request:

curl -X POST https://auth.example.com/oauth2/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d "client_id=my-client-id"

Both access tokens and refresh tokens can be revoked. Revoking a refresh token prevents it from being used to obtain new tokens. Revoking an access token marks it as inactive for introspection — it will also fail JWT signature validation at the resource server if the server checks expiry.

Response: 200 OK with an empty body (per RFC 7009 — revocation always returns 200 even if the token was already invalid).

Implicit revocation​

Tokens are also revoked implicitly:

  • When the user logs out (GET /oauth2/logout)
  • When an admin deactivates a session via the Admin UI or API
  • When the background cleanup job removes expired records