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

Both access and refresh tokens can be introspected. Each token is checked against its own expiration time, and an active response reports that time in exp. An unexpired refresh token can remain active after its paired access token expires; an expired refresh token is inactive even while the access token remains valid. Revocation, session and user checks still apply.

Active responses report aud from the submitted token as an array, including its issuer, client ID and any audiences configured when it was issued. Later configuration changes do not alter that value. jti is the submitted token’s JWT identifier, never the database row ID. Optional aud and jti fields are omitted when absent, including on refresh tokens that do not carry them.

Authentication

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

1. Confidential 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. The caller must be an active admin with a valid, unrevoked access token whose audience includes autentico-admin. An admin’s token issued only for another app does not authorize introspection. Authorized admin callers can introspect any token regardless of its issuing client.

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": ["https://auth.example.com/oauth2", "my-client-id"],
  "jti": "token-identifier"
}

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).

Public clients cannot authorize introspection with client_id alone, even if they send an arbitrary secret. Use a confidential backend or an authorized admin API bearer token. Public-client token issuance, refresh and revocation keep their existing authentication rules.

Token revocation (RFC 7009)

Admin bearer revocation requires a live token with the autentico-admin audience and a current admin role. An admin user’s token issued only for an ordinary app does not authorize cross-client revocation; rejected audience or role checks return HTTP 403 with a Bearer insufficient_scope challenge. Client-authenticated revocation retains its existing ownership checks.

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