Account recovery with Temp Code

When users are unable to authenticate through standard methods—such as SMS, email OTP, or TOTP—due to outages, technical issues, or loss of access to their registered device, customer support can assist by providing a Temp Code. The Temporary Access Code, issued manually by customer support, serves as an alternative authentication method.

This secure solution allows users to regain access to their accounts during recovery flows.

This guide shows you how to integrate a journey using the Web SDK to authenticate users with a Temporary Access Code, enabling them to restore access to their usual login credentials.

How it works

Temporary Access Code authentication combines human verification of the user's identity with online validation of a Temporary Access Code. The process begins when the user contacts customer support, who verifies their identity using security questions or other manual methods. After verification, customer support generates a Temporary Access Code (Step 6) and securely delivers it to the user via an offline method, such as a phone call or email. The user then enters the code, along with an identifier, in the client app, which invokes the account recovery journey (Step 7). Mosaic's backend validates the Temporary Access Code to complete the process.

Step 1: Create your app

To integrate with Mosaic, you'll need to create an application in the Admin Portal (if you don’t have one yet).

1. From Applications , click Add application .
2. Add the friendly application name to display in the Admin Portal.
3. Create an OIDC client: add a client display name and your website URL as a redirect URI (e.g., https://your-domain.com ), specify Client credentials as authentication method.

Upon adding a client, client credentials will be generated automatically.

Step 2: Configure SDK connection

To run this flow, you need integration with the SDK corresponding to your working environment: Web, Android or iOS.

In particular, to perform this flow, you'll need to:

• load or install the SDK (see Web , Android or iOS ).
• initialize the SDK (see Web , Android or iOS )

Step 3: Configure Temp Code

Temporary Access Code settings share the same configuration as OTP settings, which can be managed for your application in the Admin Portal > Authentication > Authentication methods > One time passcodes.

By default, the settings for OTPs and Temp Code are:

• Expiration delay : 5 minutes
• Lockout delay : 15 minutes
• Failed attempts allowed before lockout : 3

Step 4: Create journey

Configure the flow logic in the journey. Create a blank client SDK journey ( Admin Portal > Orchestration > Identity journeys). Although Temp Code authentication happens in a dedicated step, building a journey for account recovery with Temp Code primarily focuses on how to collect the user identifier and Temp Code for validation. Collect user identifier and Temp Code as custom parameters in the start journey call:

Add the Temp Code Authentication step with the following expressions in its configurations:

• External user ID : Set to @policy.request().params.external_user_id to dynamically collect the user identifier from the start journey call.
• Temporary code : Set to @policy.request().params.temp_code dynamically to collect the Temp Code to verify from the start journey call.

These parameters will later be used in the start journey call.

For the sake of this guide, add a Complete journey step as a success branch, and a Reject access step as a failure branch.

Step 5: Build UI for Temp Code input

To allow users to authenticate using a Temporary Access Code, you need to provide a UI where they can enter their User Identifier and Temporary Access Code. In this approach, the UI collects external_user_id and temp_code before the start journey call, as these values are sent as parameters directly in the start journey request. Expected flow:

1. The user enters their User ID and Temporary Access Code .
2. Clicking Login with Temporary Code triggers start journey call, passing these values as additionalParams .
3. The journey immediately processes the Temp Code Authentication step.

You will implement the start journey function based on the environment in use (see Step 7).

Step 6: Generate Temp Code

To facilitate account recovery through Customer support, include in your app functionality that enables support agents to request a Temp Code. This involves integrating a backend API call to the /v1/auth/otp/send endpoint. Customer support agents will use this feature to generate a code, which is then securely communicated to the user via offline methods (e.g., phone call, email, or secure messaging). Ensure that the generated code is tied to the user's identifier (identifier) to allow accurate validation in the Temp Code Authentication step. Note that to run the call, you'll need a Client access token to use as a bearer. For more, see our Get client access token guide. Here's an example of the call's payload:

curl -i -X POST \
  https://api.transmitsecurity.io/cis/v1/auth/otp/send \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
      "channel": "direct", // Channel to use to send the OTP
      "identifier_type": "user_id", // Type of user identifier to send the OTP (email, phone_number, user_id or username)
      "identifier": "user123", // User identifier to send the OTP
      "expires_in": 600 // Optional. Overrides the configured expiration delay in seconds
    }

It will return the code:

{
    "code": "123456"
}

In practice, at this point customer support securely provides the Temp Code to the user via a secure channel (e.g. a phone call or secure chat).

Step 7: Start the Journey

To begin the Temp Code authentication flow, using the UI built in Step 5, the client application invokes the journey by calling the Orchestration SDK. The journey expects the two parameters collected in the aforementioned UI:

• external_user_id : The user identifier.
• temp_code : The temporary access code.

The function responsible for starting the journey is located in:

• Web : src/journeyExecutor.ts
• Android : MainViewModel.kt (Android)
• iOS ViewController.swift (iOS)

This function:

1. Calls the journey with the required parameters.
2. Logs the journey response or errors.
3. Returns the journey response for further processing.

The following code is responsible for initializing the journey:

import { ido } from "./sdkState"; // Imports the IDO SDK instance

export async function startJourney() {
    await ido.startJourney(
        "temp-code-authentication", // Name of the journey
        {
            additionalParams: {
                external_user_id: "<USER_IDENTIFIER>", // Replace with actual user ID
                temp_code: "<TEMP_CODE>" // Replace with the user’s Temp Code
            }
        }
    );
}

// Additional parameters for the Temp Code journey
val additionalParams = AdditionalParams("[USER_ID]", "[TEMP_CODE]")

// Start the journey with external user ID and Temp Code
TSIdo.startJourney(binding.etJourneyId.text.toString(),
    TSIdoStartJourneyOptions(additionalParams, flowId), callback)

// Data model for passing additional parameters
data class AdditionalParams(
    @SerialName("external_user_id") val externalUserId: String,
    @SerialName("temp_code") val tempCode: String
)

// Start the journey and pass external user ID and Temp Code as parameters
TSIdo.startJourney("temp-code-authentication", options: TSIdoStartJourneyOptions(additionalParams: [
    "external_user_id": "[USER_ID]",
    "temp_code": "[TEMP_CODE]"
]))

Once the journey is invoked, the external_user_id and temp_code are passed to the Temp Code Authentication step. The user enters in the UI created in Step 5 their ID and Temp Code received by the Customer Support in Step 6. The Temp Code Authentication step verifies that the external_user_id and the temp_code are correctly associated and checks the validity and accuracy of the code entered by the user.

Upon successful validation, the user is authenticated, and the journey proceeds to the next step or branch as defined in the journey configuration. Tokens generated during authentication are accessible in subsequent steps using @policy.userTokens() and can be used in subsequent steps to grant the user access to other resources or services.