Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Rate this page:
On this page

Verify TOTP Quickstart

(information)

Info

Want to see this in action first? Check out Twilio's Code Exchange and quick deploy a sample TOTP application(link takes you to an external page).

(information)

Info

Looking for open source native libraries that generate TOTPs? Try Kotlin One-Time Password Library(link takes you to an external page) for Android or SwiftOTP(link takes you to an external page) for iOS.

Verify TOTP adds the standards-compliant TOTP (Soft Token) channel to the Verify API, so that you can let your users use authenticator apps like Authy(link takes you to an external page), Google Authenticator, or your own custom app for authentication. It's great for businesses looking for a more secure, private, and lower-cost user authentication option compared to SMS OTP. TOTP even works when the user is offline, like on an airplane. Unlike the Authy API TOTP feature, no PII from the user is required, more user registration options beyond QR codes are supported, and you can configure more code properties.

There are three main steps to use Verify TOTP:

  • Register a user by generating an RFC-6238(link takes you to an external page) compliant seed.
  • Verify that the user correctly added the seed (for example via QR code) to their Authenticator App
  • To verify a registered user, check that the code a user provided matches the code generated by the unique seed.

This Quickstart will walk you through the entire process step-by-step, starting with setting up your Twilio account all the way through verifying a user.

In this Quickstart, you will learn how to:

  1. Setup
    • Sign up for Twilio
    • Create a Verify Service
  2. Register a user and TOTP seed
    • Generate a TOTP seed
    • Generate a QR code
    • Verify a successful registration
  3. Verify a user
    • Create a Challenge
    • Update the Challenge

By the end of this Quickstart, you'll have a solid foundation for implementing Verify TOTP within your app and backend to verify users at login, transaction, and other sensitive actions.

Want a technical overview first?

Check out the Verify TOTP Technical Overview to view its data model and sequence diagrams

Technical Overview(link takes you to an external page)

Sign up for - or sign in to - Twilio

sign-up-for---or-sign-in-to---twilio page anchor
(information)

Info

Already have a Twilio account? Go ahead and skip this section.

You can sign up for a free Twilio trial account here(link takes you to an external page).

  • When you sign up, you'll be asked to verify your personal phone number. This helps Twilio verify your identity.
  • Once you verify your number, you'll be asked to create a project. For the sake of this tutorial, you can click on the "Learn and Explore" template. Give your project a name, or just click "skip remaining steps" to continue with the default.
  • Once you get through the project creation flow, you'll arrive at your project dashboard in the Twilio Console(link takes you to an external page) . This is where you'll be able to access your Account SID, an authentication token, create a Verify Service and more.

Create a Verify Service

create-a-verify-service page anchor

Go to Twilio Console > Verify > Services(link takes you to an external page) and create a new Service.

Alternatively, you can select any existing Service. However, we recommend creating a new service for testing so you don't accidentally interfere with a production environment.

Register a user and TOTP seed

register-a-user-and-totp-seed page anchor

To use Verify TOTP, you first register a user by generating an RFC-6238(link takes you to an external page) compliant seed. Then you verify that they've correctly added it to their Authenticator App for generating codes.

Create a new TOTP factor

create-a-new-totp-factor page anchor

The security of TOTP relies on a shared secret between your app and your user, and this is known as the seed. Register a user by creating a TOTP factor, which generates a seed based on a set of default configs and stores it. A corresponding Entity representing your user is also auto-created if it didn't exist.

For security reasons, it is not possible to export TOTP seeds programmatically after creation and they are not returned from the Factor API. If you do need to save seeds, we recommend performing that operation during seed creation.

When creating a TOTP factor, you can optionally pass your own seed (useful for migration scenarios) and modify the default configs. See the Factor resource for reference. Some default configs are also adjustable at the Service resource level, such that all future Factors use them. Type or paste the code sample for this step.

Create a new TOTP factor

create-a-new-totp-factor-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.entities('ff483d1ff591898a9942916050d2ca3f')
_15
.newFactors
_15
.create({
_15
friendlyName: `Taylor's Account Name`,
_15
factorType: 'totp'
_15
})
_15
.then(new_factor => console.log(new_factor.binding));

Output

_24
{
_24
"sid": "YFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"entity_sid": "YEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"identity": "ff483d1ff591898a9942916050d2ca3f",
_24
"binding": {
_24
"secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",
_24
"uri": "otpauth://totp/test-issuer:John%E2%80%99s%20Account%20Name?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=test-issuer&algorithm=SHA1&digits=6&period=30"
_24
},
_24
"date_created": "2015-07-30T20:00:00Z",
_24
"date_updated": "2015-07-30T20:00:00Z",
_24
"friendly_name": "Taylor's Account Name",
_24
"status": "unverified",
_24
"factor_type": "totp",
_24
"config": {
_24
"alg": "sha1",
_24
"skew": 1,
_24
"code_length": 6,
_24
"time_step": 30
_24
},
_24
"metadata": null,
_24
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_24
}

(warning)

Warning

Do not use Personally Identifiable Information for identity. Use an immutable user identifier like a UUID, GUID, or SID.
Verify TOTP uses identity as a unique identifier of a user. You should not use directly identifying information (aka personally identifiable information or PII) like a person's name, home address, email or phone number, etc., as identity because the systems that will process this attribute assume it is not directly identifying information.

(warning)

Warning

Use caution when changing default configs
The default configs for the TOTP code (Config.CodeLength, Config.Skew, Config.TimeStep, and Config.Alg) have been chosen for a typical TOTP use case with a 6-digit length code. Please use caution when changing these configs, as it could reduce the security of the code. For example, reducing the length of the TOTP code (Config.CodeLength) makes the code easier to guess and more vulnerable to a brute force attack. While a shorter length may be necessary for your use case, consider compensating security enhancements, such as limiting the rate at which codes can be checked, reducing Config.Skew, and reducing Config.TimeStep.

The Authy app will not be able to add TOTP tokens if default configs such as Config.CodeLength or Config.TimeStep are changed. Other publicly available authenticator apps that your users might have don't support non-default configs for all mobile OSs; see this 3rd-party analysis of authenticator apps(link takes you to an external page) for details.

Contact Twilio for further guidance.

Create a QR code

create-a-qr-code page anchor

The user needs to add the seed, and optionally metadata like Issuer and Account Name, to an authenticator app like Google Authenticator, Twilio Authy, or a custom client app that you've provided to your user. This authenticator app needs to securely store the seed and generate TOTP codes using it. A typical way for the user to add the seed is via scanning a QR code. Verify TOTP generates a standard URI (factor.binding.uri) that you can convert into a QR code for this purpose. Verify TOTP does not generate the QR code itself, but there are many free/open-source QR code generators.

For this quickstart, use qr-code-generator.com(link takes you to an external page) to quickly generate a QR code by pasting the URI.

For a real implementation, you could use one of these open-source code libraries:

Scan and add this QR with your favorite authenticator app to mimic what a user would do.

Example

example page anchor

Using this URI:


_10
otpauth://totp/Twilio:John%E2%80%99s%20Account%20Name?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=Twilio&algorithm=SHA1&digits=6&period=30

Generates this QR code using qr-code-generator.com:(link takes you to an external page)

qr_code.Rate this page:

Need some help?

Terms of service
Privacy Policy

Copyright © 2024 Twilio Inc.