Generic OTP Authentication
Authenticates a user by sending a one-time passcode (OTP) through a selectable channel (SMS, Email, or Push) and validating the entered code.
About client-facing steps
A journey is a sequence of steps that are executed when it's invoked by a client application (known as the "client"). Some steps require involvement from the client, such as to collect user input. Other steps, like validating a token, are executed in the backend by the Mosaic journey engine alone.
When invoked, the journey begins executing the steps while the client waits for further instructions. When a journey reaches a client-facing step, the journey asks the client for the required input and then waits for the client to respond. The client presents their own UI if user interaction is required, and returns input to the journey. The journey then proceeds in a similar manner until it's completed.
Description
This client-facing step authenticates a user with a one-time passcode (OTP). It combines sending and validating the OTP in a single action. When executed, the step generates an OTP (with length, expiry, retries, and lockout inherited from the global OTP method settings) and delivers it to the user through the configured channel (SMS, Email, or Push) using the selected external connection.
The journey then waits for the user to enter the code in the client application (with support for resending the OTP if needed). After the client submits the code, the step validates it. Upon successful validation, the user is authenticated and the user context is set. This context can be accessed in subsequent steps using @policy.userContext(). If validation fails, the journey follows the configured error branch.
To use this step, you must:
- Select the OTP channel in the step configuration (SMS, Email, or Push).
- Implement the client-side code to submit the OTP entered by the user back to the journey.
- Optionally expose a Resend code action in the client to trigger sending a new OTP when needed.
Prerequisites for push notifications
Before users can receive push notifications, a push token must be registered so the user’s device can accept them.
Configuration
Common
| Field | Description |
|---|---|
| External User ID | User identifier of the authenticating user, specified as an expression. |
| OTP Channel | Selects the channel to send the OTP: SMS, Email, or Push Notification. |
| Error Output Variable | Variable that stores failure reasons (e.g., no device found, provider error, OTP expired). |
| Failure Behavior | Determines the behavior in case of failure: either abort the journey or proceed to a failure branch (default). |
OTP Channel: SMS
| Field | Description |
|---|---|
| SMS Provider | Select the SMS service from the list of external connections. If the list is empty, create a connection (Management > Integration hub). |
| From | The sender of the SMS. Supports dynamic content through interpolation. |
| Recipient | An expression that resolves to a phone number. |
| Message | The content of the SMS to send. Supports dynamic content through interpolation. |
OTP Channel: Email
| Field | Description |
|---|---|
| Email Provider | Select the email service from the list of external connections:
|
| Recipients | An expression that resolves to one or more email addresses, provided as a string or an array of strings. |
| Message body | The content of the email to send. Supports dynamic content through interpolation. |
| Subject | The subject line of the email. Supports dynamic content through interpolation. |
| Sender Name | The sender of the email. Supports dynamic content through interpolation. |
OTP Channel: Push Notification
| Field | Description |
|---|---|
| Push Provider | Select the push service from the list of external connections (APNs or FCM). If the list is empty, create a connection (Management > Integration Hub). |
| Push Token | A unique identifier generated on the device by the push service (APNs or FCM). The client must register this token with Mosaic so the device can receive push notifications. |
| Notification Title | (Push only) Title text shown in the push notification. |
| Notification Text | (Push only) Body text of the push notification. May include the ${otp} variable. |
Example
Suppose a form is used to collect the user identifier (such as phone number or email). The journey then proceeds to the Generic OTP Authentication step, which is configured to send a one-time passcode (OTP) via SMS, Email, or Push.
When executed, this step sends an OTP and then instructs the client to wait for the user to enter the code. The idoServiceResponse object will include the journeyStepId set to genericOTPAuthentication. The code has to be submitted back to Mosaic via the submitClientResponse SDK call.
// WEB — Submit the OTP entered by the user
ido.submitClientResponse(
ClientResponseOptionType.ClientInput,
{
"passcode": "" // user-entered code
}
);// ANDROID — Submit the OTP entered by the user
data class OtpResult(val passcode: String)
val responseData = OtpResult(collectedOTP)
TSIdo.submitClientResponse(
TSIdoClientResponseOptionType.ClientInput.type,
responseData,
callback
)// iOS — Submit the OTP entered by the user
TSIdo.submitClientResponse(
clientResponseOptionId: .clientInput,
data: ["passcode": "[passcode]"]
)In case the client has a button for resending the OTP code, it can submit a resend request to the journey. For example:
// WEB — Request resend clicked by the user
ido.submitClientResponse(ClientResponseOptionType.Resend)// ANDROID — Request resend clicked by the user
TSIdo.submitClientResponse(
TSIdoClientResponseOptionType.Resend.type,
null,
callback
)// iOS — Request resend clicked by the user
TSIdo.submitClientResponse(clientResponseOptionId: .resend)