Journey token

In Mosaic, a journey token is a secure token issued as part of a user's interaction within a journey. It contains key information about the journey execution, actions taken, and metadata such as the token's expiration time.

Typically issued at the end of a successful journey (e.g., login, authentication, or transaction approval), the token serves as a verifiable representation of the journey execution and its outcomes. Signed by Mosaic, the token ensures authenticity and integrity.

Journey token security is maintained through validation, which ensures the token is legitimate and untampered with. By validating tokens, Mosaic ensures that only authorized users can access the system and perform sensitive actions.

Important

Journeys only return a journey token. The journey token does not expose the ID or user access token for authentication, but these are available within the journey itself and can be retrieved using @policy.userContext().

Journey tokens shouldn't be confused with user access and ID tokens returned upon successful authentication. Refer to the token reference for details on Access token and ID token structure.

Use cases for journey tokens

Journey tokens have essential applications, including:

  • User authentication : Validates that the token corresponds to an active user and has remained unchanged.
  • Signature verification : Confirms that Mosaic has signed the token, verifying its authenticity.
  • Expiry validation : Verifies the token’s expiration time, ensuring it is still valid, as tokens are time-limited.
  • Journey and context validation : Ensures that token claims, such as journey details and user context, are accurate and aligned with the session.

Token structure

When validated, a journey token returns details regarding the session, user (if specified), and journey data. Below is an example of a valid token response:

Copy
Copied
{
      "error_code": 0
      "data": {
          "aud": "mobile_app",
          "sub": "<GUID>", // Yields the user_id if the user has authenticated
          "iss": "TS",
          "jti": "be35d377-c628-478b-983a-8a21ab083817",
          "iat": 1492510931,
          "exp": 1492512731,
          "did": "b049aeac-3dc5-4222-b2d0-84159a15a6a6",
          "op": "auth",
          "external_user_id": "ron+testcreateuser22@transmitsecurity.com", // Yields the external_user_id if the user has authenticated
          "pid": "Balance", // Yields the journey ID
          "pvid": "default_version",
          "sid": "475a6191-5663-46fa-a064-03f1eb121b10",
          "dsid": "62b07542-3736-4b23-a2af-dc2523b00580"
      }
  }
Important

You can add custom claims to the token by including the Enrich journey completion token step in your journey. Any extra custom claims will be reflected in the token and appear as flat entries in the claims list. This approach allows the journey to add additional information, such as risk score or other relevant metrics, for enhanced tracking and assessment.

How token validation works

When a token is issued as part of a user journey, it includes the following critical information:

  • User identifier (if applicable)
  • Journey details
  • Token expiration time

The token should be validated by calling the token validation API to ensure its authenticity and validity before granting access to sensitive operations.

Below is an example of how to validate a token when the token is associated with a specific user:

Copy
Copied
{
  "token": "eyJraWQiOiJUUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0...",
  "uid": "user123" 
}
Note

If the token is not tied to a specific user, the uid parameter can be omitted from the validation request, and the system will still validate the token based on its other attributes. If included, the uid must match the sub claim in the token to validate alignment between the token and the user context. For more, see the token validation API reference below.

If the token is valid, the system will return details such as the user identifier (if applicable), journey information, and expiration time.

Token validation API

Overview

Endpoint Name: Token Validation API
Description: At the end of a journey, a token is issued that contains information about the authenticated user (if applicable), the executed journey, parameters, and the expiration time. This token is signed by Mosaic, ensuring that the journey was securely executed by Transmit Security. The Token Validation API allows you to verify the authenticity of this token and validate its claims.

Base URL: https://api.transmitsecurity.io

Endpoint

Method: POST

URL: /ido/api/v2/token/introspect
Authentication Required: Yes
Headers Required:

  • Content-Type: application/json
  • Authorization: Bearer <YOUR_CLIENT_ACCESS_TOKEN>

Example request

Copy
Copied
curl -X POST \
"https://api.transmitsecurity.io/ido/api/v2/token/introspect" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>" \
-d '{
    "token": "eyJraWQiOiJUUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0..."
}'

Request parameters

Parameter Type Required Description
token string Yes Token to be validated (JWT). Contains user data, journey details, etc.
Authorization string Yes Mosaic client access token (TSToken) with scope auth-control-token-user.
uid string No User ID associated with the token. If provided, it must match the sub claim for validation. Omit if not linked to a specific user.
claims_on_response boolean No Indicates if the server should return claims on successful validation.
policy string No The Journey ID that should match the data in the token.
params string No Additional parameters to validate against the original authentication request.
purpose string No Expected token purpose. Valid values: auth (Authentication), act (Access Token).

Response

Successful response (Status code: 200 OK)

Copy
Copied
{
  "sub": "lwiqd5y7jsp2xj9o6nu3b",
  "op": "auth",
  "dsid": "fd224ae8-ed65-4471-b633-7a92ef4f1611",
  "iss": "TS",
  "pid": "test-create-user",
  "external_user_id": "ron+testcreateuser22@transmitsecurity.com",
  "sid": "6751a446-0aab-4c02-a4de-6fe151e2820f",
  "aud": "default_application",
  "pvid": "default_version",
  "exp": 1727347080,
  "iat": 1727345280,
  "jti": "87db08c9-276b-4118-89cc-7234eecae4c1",
  "did": "349ec26b-dff7-48c2-bae1-2fa9ae21d251"
}
Successful response fields
Field Name Type Description
sub string User's unique identifier (user_id).
op string Operation performed during the journey (e.g., authentication)
dsid string Temporary identifier for the device session used in the journey execution
iss string Issuer of the token (typically TS for Transmit Security)
pid string Journey ID
external_user_id string The user's external identifier
sid string Temporary identifier for the journey execution
aud string Audience of the token
pvid string Version identifier
exp int Expiration timestamp of the token
iat int Issued at timestamp
jti string Unique identifier for the token
did string Temporary device ID for the journey execution
Note
  • When authentication occurs, both the sub and external_user_id fields are populated with the user_id and external_user_id , respectively. If no authentication is performed, these fields remain empty.
  • did , sid , dsid and jti are designed to support an anti-replay mechanism, to prevent unauthorized reuse of previous requests by ensuring each request is unique and resistant to duplication attacks.

Error response (Status code: 400 Bad Request)

Copy
Copied
{
  "error": "Invalid token",
  "message": "The token has expired or is invalid."
}

Error codes

Status Code Description
400 Bad Request: Token is invalid or expired
401 Unauthorized: Authorization token is missing or invalid
500 Internal Server Error: Server encountered an issue