A user access token is returned upon each successful user authentication, and describes the access that was granted to the user. Access tokens are obtained by calling the /oidc/token endpoint. These tokens are also used to authorize Mosaic API requests that require the context of a logged-in user. This describes the structure and semantics of the user access tokens returned by Mosaic.
The access token is a JWT (Json Web Token) signed by Mosaic, which includes the following claims. For how Mosaic calculates scope, permissions, and roles, see How authorization works.
| Claim | Description | Type |
|---|---|---|
| sub | Subject of the JWT (user_id). | String |
| iss | Issuer of the token, which should match the issuer returned from the /oidc/jwks endpoint. | |
| iat | Time the token was issued. | Number |
| exp | Expiration time, in epoch time format. The token must NOT be accepted on or after this time. | Number |
| aud | Audience, which is the intended recipient of the token. If a specific resource is requested, this contains the resource URI. Default is userid-api. | String |
| scope | Requested scopes that are assigned to the client, as a space-delimited string. Requested scopes that are not assigned to the client are omitted. When the flow includes a consent screen, the user must also have consented to the scope. | String |
| roles | Roles assigned to the user. | Array |
| tid | Identifier of the tenant the user requested to access. | String |
| client_id | Identifier of the client the user requested to access. | String |
| app_name | Friendly name of the application the user requested to access. | String |
| app_id | Identifier of the application the user requested to access. | String |
| act | Returned in delegated access flows and in token exchange flows. In delegated access, contains the identifier of the user to whom access was delegated in the sub subclaim. In token exchange, contains a nested actor chain that identifies the clients acting on behalf of the subject. | Object |
| permissions | Permissions from the user's roles. | Array |
| cnf | Contains X.509 certificate thumbprint (SHA-256) as a confirmation of token being bound to a specific certificate (only if token binding is enabled for mTLS or private key JWT authentication). Includes x5t#S256 key and its value. | Object |
Journeys enable you to enrich tokens with additional custom claims. Token enrichment steps (such as Enrich Access and ID Token or Enrich SSO Token) can add arbitrary key/value claims to the access token. These claims are automatically included in the token upon flow completion. You can control their placement: under a dedicated custom_claims object (default) or at the token root (placement: root). Placement is configured in the enrichment step.
When using placement: root, do not overwrite reserved JWT claims such as iss, sub, aud, iat, and exp.
Here's an example of a decoded user access token:
{
"tid": "",
"app_name": "Acme",
"app_id": "8flFllgrd1Wqiru4IGai0",
"roles": [
"smP3MD65l7hKXG6qJ-S5d"
],
"custom_claims": {
"loyalty_tier": "gold",
"risk_level": "low"
},
"jti": "IJMTqbmijVG7_LsJz-y5U",
"sub": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
"iat": 1658056533,
"exp": 1658060133,
"scope": "offline_access",
"permissions": ["read:profile"],
"client_id": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
"iss": "https://userid.security",
"aud": "userid-api"
}