Custom Token Claims

Wristband allows you to inject custom claims into the tokens generated for your application. This can reduce the need for additional database lookups when your application needs data specific to the authenticated user or tenant.

Custom token claims are configured at the application level. Tenant-level custom claims are not currently supported, meaning the claims you configure apply to tokens issued for all users across all tenants within the application.

How It Works

When a user authenticates, Wristband resolves each custom claim by evaluating its path expression against the authenticated user and tenant context. The resolved values are then injected into the requested tokens under a custom_claims object in the token payload.

For example, a claim named department using the path expression user.publicMetadata.department would appear in a decoded access token like this:

{
  "jti": "zcdy2ghb6venldifzyj2f6p6di",
  "sub": "abc123",
  "sub_kind": "user",
  "exp": 1776572978,
  "custom_claims": {
    "department": "engineering"
  },
  ...
}

If a path expression cannot be resolved (e.g., the referenced metadata field does not exist on the user or tenant), then the claim is still included in the token with a value of null.

Creating a Custom Token Claim

Custom token claims are managed under Security → Token Settings in the Application View of the Wristband Dashboard.

Each custom claim requires three fields:

• Custom Claim Name: The key that will appear under custom_claims in the token payload. Names must be unique (case-insensitive) within an application, can only contain letters, numbers, hyphens, and underscores, and must be no longer than 20 characters.
• Include In: The tokens and responses the claim will be injected into. You can select any combination of Access Token, ID Token, and UserInfo Response.
  • Access Token: A short-lived JWT used to authorize API requests. Use this when your backend needs to read the claim value directly from the token during request handling. To learn more about access tokens, see Access Token Payload.
  • ID Token: A JWT returned at the end of the authentication flow that contains identity information about the authenticated user. Use this when your frontend or application needs to read the claim at login time. To learn more about ID tokens, see ID Token Payload .
  • UserInfo Response: The response from the Wristband UserInfo API. Use this when your application fetches user information directly from Wristband rather than reading it from a token.
• Path Expression: The data source Wristband will resolve the claim value from. See Path Expressions below for the full list of supported values.

ℹ️

Note: A maximum of 20 custom claims can be configured per application.

Path Expressions

Path expressions use dot notation to reference fields from the authenticated user, tenant, or role context.

For metadata path expressions, replace <key> with the specific metadata field name you want to retrieve. Nested metadata keys are supported using dot notation, up to 4 segments deep (e.g., user.publicMetadata.subscription.plan).

Deleting a Custom Token Claim

To remove a claim, click the delete icon next to it in the claims table. Deleted claims are immediately removed from all subsequently issued tokens.

Custom token claims can also be managed programmatically via the Custom Claims API.