Verify API - Authenticate a user 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 authenticate a user trying to log in on your website, with a Push Verify push sent to their registered device.

This procedure assumes that each step in the flow is successful and that you have registered the device with 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. APP uses TsPush.init(AppContext) to contact the Telesign SDK (SDK).
2. USER opens your WEBSITE and attempts a high value action (like logging in, making a purchase, etc.)
3. WEBSITE initiates verification with YOUR SERVER.
4. YOUR SERVER initiates a verification process with Telesign VERIFY using our REST API. Include the phone number and push_app_token (obtained in the registration flow) for this user.
5. VERIFY responds with a reference ID and mobile_app_token.
6. YOUR SERVER sends a response to your WEBSITE, saying that verification is in progress.
7. WEBSITE displays a loading screen and a notification to the USER informing them that a push is on the way to their registered device.
8. WEBSITE begins polling YOUR SERVER to get final verification status. Do not poll any more frequently than once every 5 seconds.
9. Each time the WEBSITE sends a polling request, YOUR SERVER sends a request to VERIFY using our REST API to retrieve the verification process.
10. YOUR SERVER then responds to your WEBSITE telling it whether verification has succeeded yet or not.
11. Meanwhile, VERIFY has sent a request to the FIREBASE server to send the push. FIREBASE sends a PushMessage with a challenge and the appropriate mobile_app_token to your APP. Your APP has a module for receiving these pushes from FIREBASE. The challenge is to be used later and the mobile_app_token is for authentication of this event.
12. Your APP uses native OS tools to display a push modal to the USER on their registered device.
13. USER approves the push.
14. APP uses the method TsPush.finalize(answer='Approve', push_message, app_id) to report the approval to the Telesign SDK and begin finalizing the transaction. The push_message parameter includes some metadata from the Firebase push message, the mobile_app_token, and the challenge received from FIREBASE earlier.
15. The Telesign SDK reports the push to Telesign VERIFY.
16. VERIFY performs authentication on the request and then if that succeeds, changes the verification state to "VERIFIED".
17. VERIFY then responds to the SDK reporting that verification was successful.
18. The SDK sends a TsPushEvent.VerificationCompleted response to your APP indicating that verification is complete.
19. Your APP brings down the push modal.
20. The polling that you began earlier should now return {"state": "VERIFIED"} as part of the response to YOUR SERVER.
21. YOUR SERVER responds back to YOUR WEBSITE that verification is successful, and the polling loop ends.
22. YOUR WEBSITE allows the user to proceed with their high value action that initiated this verification flow.

Telesign Verify iOS SDK

1. USER opens your WEBSITE and attempts a high value action (like logging in, making a purchase, etc.)
2. WEBSITE initiates verification with YOUR SERVER.
3. YOUR SERVER initiates a verification process with Telesign VERIFY using our REST API. Include the phone number and push_app_token (obtained in the registration flow) for this user.
4. VERIFY responds with a reference ID and mobile_app_token.
5. YOUR SERVER sends a response to your WEBSITE, saying that verification is in progress.
6. WEBSITE displays a loading screen and a notification to the USER informing them that a push is on the way to their registered device.
7. WEBSITE begins polling YOUR SERVER to get final verification status. Do not poll any more frequently than once every 5 seconds.
8. Each time the WEBSITE sends a polling request, YOUR SERVER sends a request to VERIFY using our REST API to retrieve the verification process.
9. YOUR SERVER then responds to your WEBSITE telling it whether verification has succeeded yet or not.
10. Meanwhile, VERIFY has sent a request to the FIREBASE server to send the push. FIREBASE sends a PushMessage with a challenge and the appropriate mobile_app_token to your APP. Your APP has a module for receiving these pushes from FIREBASE. The challenge is to be used later and the mobile_app_token is for authentication of this event.
11. Your APP uses native OS tools to display a push modal to the USER on their registered device.
12. USER approves the push.
13. APP uses the method TsPush.finalize(answer='Approve', push_message, app_id) to report the approval to the Telesign SDK and begin finalizing the transaction. The push_message parameter includes some metadata from the Firebase push message, the mobile_app_token, and the challenge received from FIREBASE earlier.
14. The Telesign SDK reports the push to Telesign VERIFY.
15. VERIFY performs authentication on the request and then if that succeeds, changes the verification state to "VERIFIED".
16. VERIFY then responds to the SDK reporting that verification was successful.
17. The SDK sends a TsPushEvent.verificationCompleted response to your APP indicating that verification is complete.
18. Your APP brings down the push modal.
19. The polling that you began earlier should now return {"state": "VERIFIED"} as part of the response to YOUR SERVER.
20. YOUR SERVER responds back to YOUR WEBSITE that verification is successful, and the polling loop ends.
21. YOUR WEBSITE allows the user to proceed with their high value action that initiated this verification flow.