Authenticator SDK - How it works

The Authy API supports push authentication, which is a secure authentication and authorization service which can be used for scenarios such as:

• Two-factor Authentication. After a user has authenticated with a username and password, ask them to respond to a request on their device for approval to continue login or to deny it.
• Passwordless logins. Instead of two factors, use push as the primary authentication. User presents only their username to your application and they then receive a push authentication request on their phone to complete the login. The phone then becomes a trusted device used for primary authentication.
• Authorizations. Instead of securing just the login, it's important to secure high value activity in the application itself. For example a high value financial transaction, a purchase or transfer of money over $10,000. When this action is requested in the application, you can send a push auth request to one or more people asking for approval before completing the transaction.

Expand image

The image above shows an example of a push authentication approval request on a mobile device. You can see how the branding and details can be used to assist the user in making an informed decision about whether to approve or deny the request. A push notification is sent to the mobile or desktop device to prompt the user to open the request.

To successfully complete an approval request with the Authenticator SDK, the following flow must be implemented.

1. Users must be added to your Authy application.
2. Your backend application must implement the creation of push authentication approval requests.
3. Your mobile application must contain the Authenticator SDK.
4. Upon installation of the mobile app, the TwilioAuth SDK must register the user's device with the Authy service.
5. When the user performs an action (i.e. login, account update, etc) in your application that requires authentication or authorization, your application creates an OneTouch approval request.
6. The Authy service will respond with a transaction ID (UUID).
7. Your backend application then triggers a push notification to the user to alert them about the approval request or the Authy service will handle the push notification for you.
8. Your mobile application receives the push notification and gets the transaction ID (UUID) from the push notification payload.
9. Your mobile app, using the TwilioAuth SDK, will retrieve the request details and display the appropriate user interface.
10. User selects either approve or deny and the TwilioAuth SDK updates the Authy service with that information.
11. The Authy service will either send your application a callback with the updated information or you call poll the Authy service for an update to the approval request.
12. Once the request status change is known, your backend application responds appropriately (i.e. the user can login or not, the account is updated or not, etc).

The SDK will need to talk to Authy securely, and therefore all devices must be authenticated. However, the Authy API Key is powerful, so you must not hard-code API keys inside the client apps. In contrast, we give you the control over the authentication method, using the one you're currently using in your backend.

If you need to have a quick start, refer to the tutorials section where you can start integrating the SDK against a sample backend that can be deployed.

Before the users start using the TwilioAuth SDK, their mobile device must be registered with the Authy service. Here is the flow for the mobile device registration using the TwilioAuth SDK:

Expand image

The user must be added to your Authy application before you start the device registration process. Depending on how you are using OneTouch, you should be adding the user to Authy either at the time where they are creating the account in your application, or for 2FA, at the point where they are enabling 2FA for their account. When you call the Authy API for a new user registration to register the user, the Authy API will respond with the user id (Authy ID).

1. Your mobile app initiates the registration process contacting your backend application.
2. Your backend application calls the Authy service and starts the registration process sending the user's Authy ID. The Authy service will respond with a registration token.
3. Your backend application sends the registration token back to the mobile app to complete the registration process.
4. The mobile app sends the registration token to the Authy service via the TwilioAuth SDK and, if successful, gets an access token for further requests from this device.

After the registration process is completed, your mobile application can interact with Authy OneTouch approval requests.

Expand image

1. The user performs an action in your application that's protected and your backend application recognizes that a OneTouch request is required for the action to complete. Your backend application creates an approval request in the Authy service. The Authy service responds with a request ID (UUID).
2. A push notification is sent to the device, either via you backend or by Authy.
   • If you send the push notification, please ensure you include the request ID in the push notification payload.
   • If Authy is sending the push notification, the request ID will automatically sent in the notification payload.
3. Your mobile application receives the push notification, extract the request ID (UUID) from the notification payload.
4. Your mobile application uses the Authy Mobile SDK to authenticate and request the details of the approval request in the Authy service.
5. The user approves or denies the approval request using the TwilioAuth SDK. The TwilioAuth SDK digitally signs the request and sends it back to the Authy service.
6. Authy sends a OneTouch callback to your backend application and then you take the appropriate actions based on the results of that operation. Your backend application can also poll for the approval request status update.