TeleSign Developer Center

Welcome! This resource hub provides documentation and references on API & SDK integration and other product-related information.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Enterprise Push Verify APIs

READ THIS NOTE:

This documentation is intended for you if you use the Enterprise versions of TeleSign products.

You use Enterprise TeleSign products if you log in to your account at teleportal.telesign.com, use endpoints that begin with rest-ww.telesign.com, and have a designated Technical Account Manager (TAM).

If you log in to your account at portal.telesign.com, are using TeleSign's free trial, have endpoints that begin with rest-api.telesign.com, and do NOT have a TAM, you need the Standard API Docs page. (This set of APIs is not available as a Standard product.)

The Push Verify product is a bundle of REST API web services and SDKs that allow you to build and integrate two-factor authentication (2FA) and transaction verification for web-based accounts into your existing mobile application.

To implement Push Verify, you need to work in three areas:

  • Web
  • Mobile - Android SDK
  • Mobile - iOS SDK

You will need the following five REST APIs:

  • Verify Registration API - Allows you to query TeleSign to determine the current state of application registration.
  • Verify Push API - Allows you to provide on-device transaction authorization for your end users.
  • Verify Soft Token API - Allows end users to use your application on their mobile device to generate a Time-based One-time Password (TOTP) verification code / use a One Time Password (OTP) to log in to your website.
  • Backup Codes API - Used to create a collection of one-time passcodes for a supplied phone number.
  • Soft Token Notification - Allows you to anticipate when your end users need to use their soft token to generate a time-sensitive one-time passcode.

NOTE:

You must have a GitHub account and be granted permission to see the Android and iOS SDK for Push Verify. Contact your Technical Account Manager for access.

This page provides an overview of Push Verify features, implementation recommendations and integration steps, and links to resources. Push Verify is discussed in the following sections:

Push Verify Product Features

The Push Verify product allows you to:

Common Workflows

This section provides an overview of common workflows, and how the pieces of the REST API and the SDKs fit in.

Registration

Registration is completed on the mobile application. In order to use the features provided by the Push Verify product, the end user must install and register for your mobile application.

The image shows a summary of how the steps flow. The table shows the steps an end user takes, and the developer roles, tasks, and tools involved in implementation. The table is written in the third person, since it describes the work for three different roles.

StepRoleTask and Tool
1. An end user downloads the required mobile application and starts registration. Android Developer, iOS Developer (You must set up a JWT server that can be accessed by any of the developers. All developers will need to fetch tokens for various processes.) The Android and iOS developers set up an appropriate user interface using their respective Push Verify SDKs.
2. The end user provides their phone number for registration. Android Developer, iOS Developer The Android and iOS developers must collect the phone number and provide it to the appropriate Push Verify SDK (Android or iOS), depending on their implementation.
3. The end user completes registration. By default, the end user gets three chances to enter the verification code correctly. If all three attempts fail, then the end user will need to restart the registration process from the beginning. Android Developer, iOS Developer, Web Developer Android and iOS developers need to fetch a token for registration. Pass registration details to the selected Push Verify SDK.

NOTE:

If you want to allow your end users more than three attempts to enter the correct verification code, speak with your Technical Account Manager.

After registration is complete, the end user is eligible to receive push notifications on their phone if the end user agreed to receive them or request backup codes, depending on the settings enabled during registration.

Push - SIMPLE / Code Challenge

You can allow an end user to log in by completing a simple or code challenge push verification. (In a simple push verification, the end user presses allow or deny in their mobile application. In code challenge, the end user must correctly enter a code on the mobile application. The code is obtained by the end user from your website.)

This section discusses code challenge in the example and table. Simple is the same as code challenge, minus the steps for entering the code (the end user just chooses allow or deny). You send the end user a verification code on the website interface. The end user enters the verification code in your mobile application. If the code checks out, the transaction completes, if not, the transaction terminates. You do this using the Verify Push web service. The image shows a summary of how the steps flow. The table shows the steps an end user takes, and the developer roles, tasks, and tools involved in implementation. The table is written in the third person, since it describes the work for three different roles.

StepRoleTask and Tool
1. An end user tries to log in to your website. Web Developer The web developer uses the Verify Registration web service to determine if the end user is registered and has the application installed and registered. If the end user does not, ask them to install the application and register. Pass them off to the registration workflow. If the end user is registered, proceed.
2. The end user is presented with choices for how to authenticate. Web Developer Based on the results returned from the Verify Registration web service, the web developer presents the available authentication choices to the end user.
3. The end user chooses the Push - Code Challenge authentication method. Web Developer, Android Developer, iOS Developer The web developer uses the code challenge feature in the Verify Push web service. If TeleSign generates the verification code, the web developer retrieves a code and displays it on the website for the end user. If the web developer is generating the verification code, they should generate a code and display it on the website for the end user. The end user enters the code into their application. The Android and iOS developers need to catch the code, and provide it to the appropriate Push Verify SDK for their implementation. If it checks out, the end user can log in to the website.
4. The end user is notified that they can or cannot access the website, depending on how authentication went. Web Developer The web developer obtains the results of the end user's push notification by using a Get Status request. (The Get Status request is also used to send TeleSign completion data. You must send completion data if TeleSign generates codes for you. If you want information about transactions delivered to you automatically, use the Verify Transaction Callback web service.) Based on the results, the web developer allows or denies the end user access to the website, or other transaction.

Time-based One Time Password (TOTP) - Soft Token

You can allow an end user to log in using a soft token. The soft token may be obtained in the moment, or the end user may use a previously obtained backup code.

The image shows a summary of how the steps flow. The table shows the steps an end user takes, and the developer roles, tasks, and tools involved in implementation. The table is written in the third person, since it describes the work for three different roles.

1. An end user tries to log in to your website. Web Developer The web developer uses the Verify Registration web service to determine if the end user is registered and has the application installed and registered. If the end user does not, ask them to install the application and register. Pass them off to the registration workflow. If the end user is registered, proceed.
2. The end user chooses an authentication method. Web Developer Based on the registration details, obtained using the Verify Registration web service, the web developer presents the available authentication choices, or the choices appropriate to their specifications. For this example, assume all choices are available: Simple, Code Challenge, Soft Token, and Backup Codes.
3. The end user chooses the Soft Token authentication method. Web Developer, Android Developer, iOS Developer The web developer uses the Mobile Device Soft Token Notification web service to anticipate the end user's choice of soft token, and send a push notification to their application. (Optional) The Android and iOS developers can use the appropriate Push Verify SDK to display a notification providing the token in the application for the end user. When the end user opens the application, their soft token will be immediately available for use. The end user enters the code provided by the token into the authentication field on the website (the web developer needs to set up the field). The web developer sends the information provided by the end user to the Verify Soft Token web service. The results of the transaction are provided to the web developer immediately. A successful response should allow the end user to access the website, otherwise the user should not be granted access.

Backup OTP Code - Soft Token

In the event that your end user loses their phone, they will need a different way to authenticate themselves. Using the Mobile Device OTP web service, you can retrieve up to ten backup codes at once for the end user. The end user stores them for use with the soft token verification method. You can see the flow for soft token verification in the section Time-based One Time Password (TOTP) - Soft Token above.

For more information, refer to the Generate Backup Codes (REST) page.

Push Verify Product Resources

A link is provided for each product resource here. Push Verify includes the following REST API web services, Push Verify SDKs, and tools:

Enterprise Push Verify APIs