How to use the Authy API with Google Authenticator (or any compatible authenticator app)

How to use the Authy API with Google Authenticator (or any compatible authenticator app)

TOTP, or Time-based One-time Passwords, is a way to generate short lived authentication tokens commonly used for two-factor authentication (2FA). The algorithm for TOTP is defined in RFC 6238, which means that the open standard can be implemented in a compatible way in multiple applications. You might be familiar with TOTP from apps like Authy or Google Authenticator, but there are a lot of other options including Duo and Microsoft Authenticator.

Getting users to enable 2FA is half the battle of improving account security, so I recommend giving your customers flexibility over which authenticator app they use.

The Authy API (connected to, but different than the Authy App) defaults to enrolling the user in the Authy App but this post will show you how to use the API in a way that lets your customers use the authenticator app of their choice.

How does TOTP work?

Inputs to the TOTP algorithm include a secret key and your system time. Those get put through a one-way function that creates a truncated, readable token. Because the inputs are available offline, the whole method works offline. This is a great option for users that may have unstable cellular connections for receiving SMS 2FA or for users who want a more secure channel than SMS 2FA.

Here's a look at how the Authy Application prompts a user to add a new account. We recommend scanning a QR code, but you can also enter the key manually. This is how the account and the authenticator app sync the secret key.

How to implement TOTP 2FA in your application

We recommend using the Authy API to implement TOTP in your application because it:

• manages passcode generation and checking for you
• is SOC2 compliant
• includes our end-user support
• also has SMS, Voice and email channels to support fallback or user choice

To register a user of your application for any authenticator app takes a couple steps.

First, sign in to your Twilio account (or create a new account) and create an Authy application in the Twilio console.

Next, enable generic TOTP tokens in the console. Scroll to the bottom and "Save" your changes.

In order to validate TOTP codes, register each user with the API to generate a unique Authy ID for each user.

You can register users to your application in one of three ways

1. In the console (requires user's phone number and email address)
2. With the Authy API (with the user's phone number and email address)
3. With the Authy API (without PII like phone number or email)

Registering users to your app using the Twilio Authy Console

From the Users tab of your Authy application in the console, click the red plus sign to add a new user. You'll need your user's email address and phone number.

Registering users to your app using the Authy API

There are two ways to add a user with the API: with and without PII. We'll walk through the example that uses PII here.

Make a request to the Users resource to create a new user with the Authy API Key for your application. This example uses cURL, but you can do this in the language of your choice - see examples in more languages in the docs.

You can find your Authy API key in the console under your Authy Application's settings tab:

Register the user with the following command:

Or - follow the instructions in the documentation for adding a user without PII.

All of these methods will return an Authy ID for the newly registered user. Save that with your user records since it's a required parameter for subsequent API requests.

Create a QR code to allow users to onboard with Google Authenticator or the TOTP app of their choice

At this point, the user is enrolled with the Authy App. As long as they have signed up for the client app (iOS, Android, or Desktop) with the same phone number you used to register them, they will automatically have your account as one of the tiles inside the Authy App.

If the user decides they want to use a different app, you'll need to create a QR code so they can sync the secret key with the authenticator app of their choice.

Create a QR code with the following command. We recommend putting something identifiable in the label field so the user knows which username or email this authentication factor is tied to:

This will return the following JSON:

The secret keys encoded in the QR codes are valid for 24 hours. After that, it will expire and you will need to generate a new QR code. Display the QR code at the link to your end user so they can scan it with the app of their choosing. Here's how this shows up in Google Authenticator after I scan the QR code:

Before you mark a user as "2FA enabled" make sure they complete at least one successful verification with their new authenticator app setup.

How to Verify a TOTP code with the Authy API

Use the following command, replacing the TOKEN and AUTHY_ID with the appropriate values.

Running this command with a generic authenticator token like one from Google or Microsoft Authenticator will return the following:

There's a lot of null data about the device, because we don't know anything about the device the user has. Alternatively if the user uses an Authy application token, the API response will include additional information available about their device.

The Authy helper libraries for Python, Ruby, PHP, Node.js, and Java support this API call too. Learn more in the documentation for Authy one-time passwords.

What's next?

Congratulations on getting your users enrolled in 2FA! For more flexibility - check out the API docs for sending one-time passwords via SMS, voice, or even email. The beauty of the Authy API is that no matter which method you use to send the token, you can check the tokens with the same API.

Need help getting your users to enable 2FA? I wrote about how to incentivize 2FA. If you want to learn more, check out my presentation on 2FA channels and their tradeoffs from BSides San Francisco this year.

Do you have questions about how to get started with 2FA? Leave me a comment or find me on Twitter @kelleyrobinson. I can't wait to see what you build.