Access token reference

Access tokens are JWTs (RFC 9068) signed by the environment's active key and published at /.well-known/jwks.json. The JOSE header carries typ: at+jwt, so a resource server can refuse an ID Token presented in its place. Every grant — authorization code, refresh, client credentials, device, CIBA and token exchange — mints through the same TokenIssuer, so the shape below does not depend on how the token was obtained.

Claims

Audience

aud is decided once per token by the audience resolver:

When a token is for a registered API its scope holds only that API's scopes plus the protocol scopes (openid, profile, email, offline_access, organizations, groups, feature_flags). The rules and the ownership model are in APIs and scopes.

A refresh re-mints the scopes and audience the original token was granted, never more.

Verifying one

A resource server should check iss, the signature against the JWKS, typ: at+jwt, exp, that its own identifier is in aud, and the scopes or permissions it needs. A string aud and an array aud are both valid JWT; compare by membership.

Every token an app holds carries that app's client_id, including one issued to a person signed in through it. Do not treat client_id as the caller's identity on its own. Only a machine token (client_credentials) acts as the app: active, sub equal to client_id, and no act claim. Introspection::isMachine() checks all three:

if ($token->isMachine()) {
    // The app itself: its own secrets, its own grants, service-to-service questions.
} else {
    // A person ($token->subject), through that app. Hold them to their own access.
}

Resource-server introspection

A confidential client can introspect its own tokens at /oauth/introspect. A resource server accepting tokens minted to another client needs an explicit host-side grant:

// config/cbox-id.php, within oauth.introspection:
'resource_servers' => [
    'registered-resource-client-id' => ['https://api.example.com'],
],

The default is an empty map. Register the API audience and confidential client normally; then an operator grants only the exact audience that server owns. API-to-app RBAC linkage (oauth_apis.client_id) does not grant introspection access. This map is not a dynamic client-registration field. No wildcard, URI-prefix, issuer-audience or multi-audience matching is performed.

The caller authenticates using its own confidential-client credentials and sends the original access token as token. A valid grant returns the normal introspection response, including the original client_id, subject, audience, token type and authentication context. The resource server must still check its audience, required scopes, caller integration delegation and current application permissions. A DPoP token's cnf must be enforced; an introspection grant does not convert it into an ordinary bearer.

Cross-client introspection also checks current organization status and, for user tokens bound to an organization, active membership. Removed or suspended members and inactive organizations return only {"active": false}. Organization-owned resource clients cannot inspect another organization's token. Environment scoping and token revocation remain in force. Removing a configured grant stops subsequent cross-client introspection without revoking the original client's token. Own-token introspection behavior is unchanged.

The ResourceIntrospectionAccess contract can be rebound by hosts that keep these explicit grants in another authoritative store.