Integration of User Login via SMS or Email

  • Published on Sep 9, 2025
  • 5 minute(s) read
Prev Next

With OneSpan Cloud Authentication you can implement functionality for your users to log in to your web application through the use of a virtual authenticator via the OneSpan Cloud Authentication platform. A one-time password (OTP) is generated by the authentication component and delivered via SMS or email, depending on the policy set within the OneSpan Cloud Authentication component. OneSpan Cloud Authentication offers two modes to integrate the user login flow: the synchronous and the asynchronous login mode.

User login via notification—process overview

The user attempts to log in to the web server with their credentials. If this first login step is successful, they receive a notification that contains an OTP. Depending on the selected notification mode, the OTP will be delivered to the user as SMS (via the SMS service) to the mobile phone number associated with this user in the user profile or the email address of the user if an email account has been defined for this user.

The user can extract the OTP from the message and continue the login procedure, including the OTP in the request to the TID web server. The TID web service receives the OTP and checks it against the Authentication component. When the OTP validation is successful, the login can be completed.

Integration of user login via notification with SMS

Virtual authenticator OTP via SMS

Virtual authenticator OTP via SMS

Sequence of a user login operation via notification with SMS

  1. The user initiates the login operation and triggers the client application to send a login request. This request includes the following parameters:

    • authenticator user

    • authenticator domain

    • session identifier

    The user's credentials (static password) must not be included in the request input! Instead of their credentials, the user needs to provide the keyword votp in the passkey field.

  2. OneSpan Cloud Authentication responds as follows:

    1. The TID web service requests OneSpan Cloud Authentication to create an OTP and to deliver it via SMS as defined in the user settings.

    2. The web service returns the OTP to the client application.

  3. The user collects the OTP received via SMS.

    1. The user attempts to log in with the retrieved OTP.

  4. The client application sends the OTP to the web service.

  5. The web service validates the OTP with OneSpan Cloud Authentication. The validation result includes the serial number of the used authenticator .

    1. The web service returns to the client application that the authentication has been successful.

    2. The client application checks the status of the login request with the web service.

Integration of user login via notification with email

Virtual authenticator OTP via email

Virtual authenticator OTP via email

Sequence of a notification user login operation via email

  1. The user initiates the login operation and triggers the client application to send login request. This request includes the following parameters:

    • authenticator user

    • authenticator domain

    • session identifier

    The user's credentials (static password) must not be included in the request input! Instead of their credentials, the user needs to provide the keyword votp in the passkey field.

  2. OneSpan Cloud Authentication responds as follows:

    1. The TID web service requests OneSpan Cloud Authentication to create an OTP and to deliver via email as defined in the user settings.

    2. The web service returns the OTP to the client application.

  3. The user collects the OTP received via email.

    1. The user attempts to log in with the retrieved OTP.

  4. The client application sends the OTP to the web service.

  5. The web service validates the OTP with OneSpan Cloud Authentication. The validation result includes the serial number of the used authenticator.

    1. The web service returns to the client application that authentication has been successful.

    2. The client application checks the status of the login request with the web service.

Customized delivery method of the virtual one-time password (OTP)

It is also possible to customize how the virtual one-time password (OTP) is delivered to the user. You can for instance use your own gateway or another special, customized communication channel. With this, it is possible to receive the virtual OTP in the request response session. To ensure that the generated virtual OTP is never returned directly to the user, it is stored inside a session that must be queried separately.

Mild security risk

When you use this feature, the virtual OTP is returned in the same session in which it has been requested. Because this forms a mild security risk, be advised to treat the virtual OTP as sensitive data. Make sure the data is transmitted via a different secure channel than the one in which it was requested (e.g. an SMS sent to a different device than the one from which the request was sent).

If you enable this feature this does not deactivate the original delivery method for virtual OTPs! The custom delivery has to be requested in the request payload on a per-request basis.

Prerequisites

  • A virtual authenticator (e.g. VIR10) is assigned to the relevant user account.

  • The vdpDeliveryMethod field in the user account settings must be set to Default for the custom delivery to work correctly.

Necessary integration steps

You can trigger the customized virtual OTP delivery either with an administrative command or via user authentication.

To integrate the customized delivery method via an administrative command

  • To integrate the feature via an administrative command with your back-end system, integrate it into the POST /authenticators/{serialNumber}/applications/{applName}/generate-votp endpoint.
    This endpoint will be triggered when your workflow requires the generation of a virtual OTP at some stage.

  • Use the keyword Response in the deliveryMethod field of the GenerateVOTPInput object. The response will be 200 OK, the GenerateVOTPOutput payload will contain the field votp.

To provide the customized delivery method via user authentication

To provide the feature via user authentication, integrate it into the following endpoint:

Integration into POST /users/{userID@domain}/login

To ensure that the generated virtual OTP is never returned directly to the user, it is stored inside a session that must be queried separately.

The delivery of the virtual OTP is triggered when the keyword votpCustomDelivery is sent via the passKey field of the LoginInput payload. The response is 200 OK, the LoginOutput payload contains the following fields:

  • sessionStatus, with the value pending

  • requestID, with a generated value, e.g. 47543e06-1c11-49b8-94ed-d9501f7fd3f2

After the delivery has been triggered, the GET /sessions/{requestID} endpoint must be queried. The response will contain the field votpResponse with the generated virtual OTP which you can deliver to your user. It will also contain the serial number of the used authenticator to ensure traceability of the transaction.

Use of this feature is optional, it is not provided by default. Contact OneSpan Support for activation. Once enabled, the virtual OTP will be delivered with the same method for all tenants that are grouped in the same Authentication component deployment as the one where this feature has been enabled.