ID tokens

This describes the structure and semantics of the ID token returned by Transmit upon successful user authentication.

Default claims

Default claims are returned in the ID token without being requested. These claims include standard JWT claims, some basic user profile data, and info about their authentication.

Field Description Type
sub User's unique identifier (user_id). String
tid ID of the Transmit Security tenant. String
aud Client ID of the application associated with the token request. String
exp Token expiration time, as a unix-epoch encoded timestamp in seconds. Number
iat Time the token was issued, as a unix-epoch encoded timestamp in seconds. Number
iss Token issuer, which should be: (for global tenants, non EU and CA) or (for EU tenants), (for CA tenants). String
auth_time Time the user was authenticated, which can be different from the token issue time (if the user was already logged in when the token was requested). Number
amr Authentication methods used: eml, eotp, sms, pwd,social, webauthn,mfa. Array
acr Requested ACR values that were satisfied, as a space delimited string. String
webauthn Returned only if WebAuthn was used. Contains info about the devices used, the last time the user logged in, and the first and last time the authenticating device was used. Object
webauthn_username Returned only if WebAuthn was used. Contains the username used (UUID) used for WebAuthn. String
new_user Indicates if a new user was created as part of the authentication flow. Boolean
groups Groups to which the user belongs. Array
approval_data Returned only in transaction signing flows. Contains info about transaction type, payment amount, currency, payment method, and payee info. Object
organization Organization to which the user belongs. String

Custom claims

Aside from the default claims, additional claims may be added to the token by request (see Requesting claims). This includes user roles and permissions, additional user profile data, and custom data set by your application.

The following claims can be requested:

Field Description Type
fname User's first name. String
mname User's middle name. String
lname User's last name. String
email User's primary email. String
email_verified Indicates if the user's primary email is verified. Boolean
phone_number User's primary phone number. String
phone_number_verified Indicates if the user's primary phone number is verified. Boolean
username Username used to identify the user for password login (unless a primary email will be used instead). Defined only if a password was set for the user. String
secondary_phone_numbers List of user's secondary phone numbers (objects). Array
secondary_emails List of user's secondary emails (objects). Array
birthday User's birthday as YYYY-MM-DD. String
address User's address. Object
picture The picture of user, specified as a URL. String
language The language of the user, as provided by the browser using the Accept-Language header field. String
roles List of roles IDs assigned to the user. Array
role_values List of human-readable main and custom roles assigned to the user. Array
permissions List of permissions delegated to the user. Array
created_at Date user was created in the tenant. Number
last_auth Date user last authenticated. Number
external_account_id User identifier in an app, set by the app. String
external_user_id User identifier in a tenant, set by the app. String
app_name Name of the app the user is associated with. String
custom_data Custom data object for tenant user info. Object
custom_app_data Custom data object for app-related user info. Object
custom_group_data Custom data object for group info. Object

For detailed structure of the user profile data, see the User Object returned in the result.

Requesting claims

Additional claims are requested using the claims request parameter, as defined by the OIDC standard. For example, the following claims parameter value is used to request all the user's permissions:

      "permissions": null

Your custom user data can be added to the ID token by requesting the custom_data or custom_app_data claims. If their value is set to null in the request, the entire object will be returned. However, you can also include only a subset of fields in these claims by using a fields member to specify the names of the fields to return as an array.

The following example is used to request 2 fields (named field1 and field2) from the tenant-level custom data and another field (named field3) from the app-level custom data:


The payload of the custom_data or custom_app_data claim cannot exceed 100KB.

Token example

Here's an ID token that includes the user's secondary emails and specific fields from the custom data:

  "sub": "ufnbfps4ki0qm1twdo79g",
  "tid": "6oijksdf9esfehwjkfey9",
  "email": "",
  "groups": [],
  "new_user": false,
  "amr": [
  "email_verified": true,
  "secondary_emails": [
      "value": "",
      "email_verified": false
  "custom_data": {
    "field1": "value1",
    "field2": "value2"
  "custom_app_data": {
    "field3": "value3"
  "auth_time": 1674562962,
  "at_hash": "gUWf6OJKHDKUAYDAIX7LQ",
  "aud": "pVEZaxFuQyCQ95NNhiBLe",
  "exp": 1674566580,
  "iat": 1674562980,
  "iss": ""