How to build TOTP support with the Verify API and Google Authenticator

November 18, 2021
Written by
Reviewed by

Build TOTP support with the Verify API and Google Authenticator

While One-Time Passcodes (OTPs) delivered via SMS or email have a place, authenticator apps like Authy and Google Authenticator provide stronger authentication with time based one time passcodes (TOTP). Not only do TOTPs work offline, but they're based on a standardized algorithm so can be used without PII and with a variety of authenticator apps.

Learn more about what TOTP is and its benefits in our glossary.

Example TOTPs in the Google Authenticator app

The Twilio Verify API makes it easy to initiate and verify TOTPs, now available in public beta. Let's see how to get started with Verify TOTP in under 5 minutes.

Prerequisites for sending One-Time Passcodes

Before you can send an OTP you'll need:

Copy your Service SID (starts with VA):

Verify service with name "TOTP sample app"

Quick Deploy a Twilio Verify application

Make sure you're logged in to Twilio and head over to Twilio's Code Exchange for the TOTP project and paste in your Verify Service SID:

Quick deploy form with logged in account name and Verify service SID filled in

Next, click "Deploy this application". After a few seconds you should see a button to "Go to live application": click that to head to your new Verify application.

You'll be prompted to enter a username, which will show up in the application name for the authenticator app.

screenshot of the TOTP sample application with a form to enter your username and set up 2FA

When you click "Set up two-factor authentication", the API is creating a new TOTP Factor. This is how the Verify API connects a user (identity), the TOTP channel, and your app. Each Factor returns the secret seed and URI used to create a QR code.

The application will display both a QR code and the seed.

QR code to scan with a form field to enter the code generated by your authenticator app

Scan the QR code in your authenticator app and enter the 6 digit code to verify the factor.

sample TOTP in google authenticator

Before you can use this channel for ongoing authentication, the user must verify the Factor to ensure that setup was successful. After sharing the seed via a QR code or secret key, this authentication channel is available offline.

Note: unverified Factors will be deleted between 1 and 24 hours after being created.

After you successfully verify the Factor you can use the form to test additional verifications. Only one verification is allowed per code, so you'll need to wait at least 30 seconds before trying again.

Customize your TOTP setup

This demo uses default settings for things like code length, time step, and skew. Learn more in the documentation about how to create a factor with different settings, like increasing the code length from 6 to 8 or the time step from 30 seconds to 45 seconds.

--data-urlencode "Config.TimeStep=45" \
--data-urlencode "Config.CodeLength=8" \
--data-urlencode "FriendlyName=Kelley's Phone" \
--data-urlencode "FactorType=totp" \

How to use the Verify TOTP Quick Deploy application

You might have noticed that this application doesn't actually protect anything, but if you're like me, you love having code to copy and modify.

From the main page of your deployed code exchange project, click "Edit this application". You can also find this by navigating to the Functions section of the Twilio Console. From there you can edit, save, and deploy changes directly from the Twilio Console. The screenshot below shows the code editor for the /verify-new-factor function.

screenshot of the twilio console functions editor

You can also find the code on GitHub and use this as a starting point for building TOTP support into your own application.

Check out the Verify TOTP quickstart and documentation for Factors and Challenges for more information. The TOTP technical overview is also a great resource for understanding how all of this fits together.

You also might like these Quick Deploy projects for more inspiration:

I can't wait to see what you build!