Verify API - Authenticate a user with Push Verify

📘

NOTE:

To add this product to your account, contact a Telesign expert. 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.

Before you begin

• Review Verify API - Get started and its key terms for Verify API.
• 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.
• Implement Verify API and Verify Mobile SDK to your website as well as to your mobile app. This is required in order for Push Verify to work successfully.

Steps

Telesign Verify Android SDK

1. APP uses TSVerify.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 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 informs the USER 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 TSVerify.finalizeVerificationStamp 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 TSVerify.VerificationCompleted event to your APP indicating that verification is complete.
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.

Telesign Verify iOS SDK

1. You don’t need to explicitly initialize TSVerify, it will be auto-initialized the first time you use the 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 informs the USER 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 TSVerify.finalizeVerificationStamp 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 TSVerifyEvent.verificationCompleted event to your APP indicating that verification is complete.
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.