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

How to 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.

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:

• A Twilio account - sign up or sign in
• A Verify Service which you can create in the Twilio console. The service name will be used as the issuer and show up in the Authenticator app (e.g. Twilio or Segment above).
• An authenticator app of your choosing such as Authy, Google Authenticator, or totp.app

Copy your Service SID (starts with VA):

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:

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.

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.

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

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.

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.

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:

• SMS verification with retry logic and voice fallback
• Phone Number Lookup
• One-Time Passcode Verification (OTP)

I can't wait to see what you build!