Verify API - Register a new device with Push Verify

📘

NOTE:

Contact our sales team for availability of Push Verify in your region. This product is available for full-service accounts only.

This page explains step-by-step how to register a user's new device with Push Verify, so they can use it to approve pushes later when logging in on your website.

This procedure assumes that each step in the flow is successful and that the device has not already been registered for Push Verify.

These instructions also assume the use of a verification policy with:

  • Push Verify set as the primary verification method.
  • SMS one-time passcode (OTP) set as the fallback verification method.

📘

NOTE:

Android Verify SDK events and iOS Verify SDK events for the Push Verify verification method are sent as responses to SDK methods. You do not need to subscribe to these events.

Before you begin

Install the Telesign Verify Android SDK or Telesign Verify iOS SDK, depending on your specific needs. Contact Telesign Customer Support or your Telesign contact to get access.

Steps

Telesign Verify Android SDK

  1. USER downloads, installs, and opens customer's mobile app (APP).
  2. APP uses TsPush.init(AppContext) to contact the Telesign SDK (SDK) to begin the registration process.
  3. APP prompts USER to log in with phone number, username, and password.
  4. USER enters this info on the APP.
  5. APP sends this info to the customer's BACKEND.
  6. BACKEND responds with customer auth token.
  7. APP uses TsPush.isRegistered() to check with the SDK if the device is registered for Push Verify yet. The SDK indicates that it is not.
  8. APP requests a push app token from the FirebaseSDK using FirebaseSDK.getToken().
  9. APP sends a request to register for push verification to the BACKEND, including customer_auth_token, push_app_token, and phone_number.
  10. BACKEND checks if this customer auth token is already registered for push verification. It is not.
  11. BACKEND makes a Create verification process API request to TELESIGN, including the phone number and a flag (push_registration=true) to indicate that this verification process is for the purpose of registering for push verification.
  12. TELESIGN sends an SMS OTP to the end user at this phone number.
  13. TELESIGN sends a response to BACKEND with a reference ID identifying the transaction and a mobile app token.
  14. BACKEND sends this mobile app token to APP. In a later step, the Telesign SDK will use this token as an authentication credential for requests to TELESIGN.
  15. APP prompts USER to enter the SMS they received.
  16. USER enters the correct OTP.
  17. APP generates an app ID, using this format: com.{app name}.{app version number}. For example: com.your.app:1.2.0
    APP saves this value for later use.
  18. APP sends the asserted OTP to the SDK using TsPush.register(phone_number, app_id, mobile_app_token, otp_code).
  19. SDK stores this number in AppData
  20. SDK passes this OTP and app ID on to TELESIGN.
  21. TELESIGN checks the asserted OTP against the original OTP. If they match, TELESIGN sends a response to the SDK indicating that the validation was successfully completed.
  22. SDK sends a TsPushEvent.RegistrationCompleted response to the APP reporting that verification is complete.
  23. APP uses TsPush.isRegistered() again to check with the SDK if the device is now registered for Push Verify. The SDK responds that it is now registered.
  24. APP allows USER to log in.
A diagram that explains the workflow of your integration when it registers a device for Push Verify.

Push Verify - Register a device - Android

Telesign Verify iOS SDK

  1. USER downloads, installs, and opens customer's mobile app (APP).
  2. APP prompts USER to log in with phone number, username, and password.
  3. USER enters this info on the APP.
  4. APP sends this info to the customer's BACKEND.
  5. BACKEND responds with customer auth token.
  6. APP uses TsPush.isRegistered() to check with the SDK if the device is registered for Push Verify yet. The SDK indicates that it is not.
  7. APP requests a push app token from the FirebaseSDK using FirebaseSDK.getToken().
  8. APP sends a request to register for push verification to the BACKEND, including customer_auth_token, push_app_token, and phone_number.
  9. BACKEND checks if this customer auth token is already registered for push verification. It is not.
  10. BACKEND makes a Create verification process API request to TELESIGN, including the phone number and a flag (push_registration=true) to indicate that this verification process is for the purpose of registering for push verification.
  11. TELESIGN sends an SMS OTP to the end user at this phone number.
  12. TELESIGN sends a response to BACKEND with a reference ID identifying the transaction and a mobile app token.
  13. BACKEND sends this mobile app token to APP. In a later step, the Telesign SDK will use this token as an authentication credential for requests to TELESIGN.
  14. APP prompts USER to enter the SMS they received.
  15. USER enters the correct OTP.
  16. APP generates an app ID, using this format: com.{app name}.{app version number}. For example: com.your.app:1.2.0
    APP saves this value for later use.
  17. APP sends the asserted OTP to the SDK using TsPush.register(phone_number, app_id, mobile_app_token, otp_code).
  18. SDK stores this number in AppData
  19. SDK passes this OTP and app ID on to TELESIGN.
  20. TELESIGN checks the asserted OTP against the original OTP. If they match, TELESIGN sends a response to the SDK indicating that the validation was successfully completed.
  21. SDK sends a TsPushEvent.registrationCompleted response to the APP reporting that verification is complete.
  22. APP uses TsPush.isRegistered() again to check with the SDK if the device is now registered for Push Verify. The SDK responds that it is now registered.
  23. APP allows USER to log in.
A diagram that explains the workflow of your integration when it registers a device for Push Verify.

Push Verify - Register a device - iOS