Reference Access Tokens

Client applications can choose the access token format with Access Token Type.

Value	Behaviour
SelfContainedJwtToken	Default. ProAuth returns a signed JWT access token. Resource servers can validate it locally with issuer metadata and signing keys.
ReferenceToken	ProAuth returns an opaque 32-byte base64url handle. The signed JWT access-token payload is stored server-side and resource servers validate the handle through token introspection.

Reference tokens are useful when immediate revocation and smaller tokens are more important than offline resource-server validation. Because the token contents are not visible to clients or intermediaries, APIs must call the introspection endpoint to get claims, scopes, expiry, audience, and client information.

Resource Server Validation

Resource servers that accept reference tokens must call the introspection endpoint:

POST /connect/introspect
Authorization: Basic <client credentials>
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token

An active reference token returns the same access-token payload data that a JWT client would receive locally, including scope, client_id, aud, sub, iss, iat, and exp. Missing, expired, or revoked reference tokens return active: false.

Revocation And Cleanup

Revoking a reference access token marks the stored token payload revoked immediately, so introspection returns inactive right away. With the database token backend, revoked and expired token rows are removed by the normal token prune job. With the Redis/state-store backend, revoked tokens are retained for the configured revocation TTL, or hard-deleted immediately when that TTL is 0.