Verify TOTP Quickstart

You can sign up for a free Twilio trial account here.

• 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. This is where you'll be able to access your Account SID, an authentication token, create a Verify Service and more.

Go to Twilio Console > Verify > Services 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.

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

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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createNewFactor() {
11
  const newFactor = await client.verify.v2
12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .entities("ff483d1ff591898a9942916050d2ca3f")
14
    .newFactors.create({
15
      factorType: "totp",
16
      friendlyName: "Taylor's Account Name",
17
    });
18

19
  console.log(newFactor.binding);
20
}
21

22
createNewFactor();

1
{
2
  "sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "identity": "ff483d1ff591898a9942916050d2ca3f",
7
  "binding": {
8
    "secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",
9
    "uri": "otpauth://totp/test-issuer:John%E2%80%99s%20Account%20Name?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=test-issuer&algorithm=SHA1&digits=6&period=30"
10
  },
11
  "date_created": "2015-07-30T20:00:00Z",
12
  "date_updated": "2015-07-30T20:00:00Z",
13
  "friendly_name": "Taylor's Account Name",
14
  "status": "unverified",
15
  "factor_type": "totp",
16
  "config": {
17
    "alg": "sha1",
18
    "skew": 1,
19
    "code_length": 6,
20
    "time_step": 30
21
  },
22
  "metadata": null,
23
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
24
}

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 to quickly generate a QR code by pasting the URI.

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

• Node: https://github.com/soldair/node-qrcode or https://www.npmjs.com/package/otplib
• Go: https://github.com/skip2/go-qrcode
• Python: https://pypi.org/project/PyQRCode/
• PHP: https://github.com/endroid/qr-code

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

Using this URI:

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:

Expand image

Scanning this QR using the Twilio Authy app generates this token:

Expand image

Instead of a QR code, you can pass the seed to the user's authenticator app by displaying it for manual entry by the user (supported by most commercial authenticator apps), including it in a deep link, or sending it via another authenticated channel.

When the Factor is first created, it's in an "unverified" status. To verify the Factor, the user needs to demonstrate that they are able to generate a correct code based off of the seed.

Use the code generated by your authenticator app and type or paste the code sample for this step.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateFactor() {
11
  const factor = await client.verify.v2
12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .entities("ff483d1ff591898a9942916050d2ca3f")
14
    .factors("YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15
    .update({ authPayload: "293412" });
16

17
  console.log(factor.status);
18
}
19

20
updateFactor();

1
{
2
  "sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "identity": "ff483d1ff591898a9942916050d2ca3f",
7
  "date_created": "2015-07-30T20:00:00Z",
8
  "date_updated": "2015-07-30T20:00:00Z",
9
  "friendly_name": "friendly_name",
10
  "status": "verified",
11
  "factor_type": "totp",
12
  "config": {
13
    "alg": "sha1",
14
    "skew": 1,
15
    "code_length": 6,
16
    "time_step": 30
17
  },
18
  "metadata": null,
19
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
20
}

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function listFactor() {
11
  const factors = await client.verify.v2
12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .entities("ff483d1ff591898a9942916050d2ca3f")
14
    .factors.list({ limit: 20 });
15

16
  factors.forEach((f) => console.log(f.sid));
17
}
18

19
listFactor();

1
{
2
  "factors": [
3
    {
4
      "sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
      "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
      "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8
      "identity": "ff483d1ff591898a9942916050d2ca3f",
9
      "date_created": "2015-07-30T20:00:00Z",
10
      "date_updated": "2015-07-30T20:00:00Z",
11
      "friendly_name": "friendly_name",
12
      "status": "unverified",
13
      "factor_type": "totp",
14
      "config": {
15
        "alg": "sha1",
16
        "skew": 1,
17
        "code_length": 6,
18
        "time_step": 30
19
      },
20
      "metadata": null,
21
      "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
22
    }
23
  ],
24
  "meta": {
25
    "page": 0,
26
    "page_size": 50,
27
    "first_page_url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors?PageSize=50&Page=0",
28
    "previous_page_url": null,
29
    "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors?PageSize=50&Page=0",
30
    "next_page_url": null,
31
    "key": "factors"
32
  }
33
}

Congratulations! You've just completed the first Verify TOTP sequence: register user and TOTP seed. The second sequence is to verify (authenticate) a user with their authenticator app, whenever they need to login to your app or perform some other sensitive action. Read on for the step-by-step instructions.

To verify a user, the user needs to read the latest code generated by their authenticator app and provide it to you. Then you need to create a Challenge and include the code as the AuthPayload. If the code is correct, then the Challenge will be created with a status of approved. Incorrect codes will result in a Challenge that is created with a status of pending, and will eventually expire. In the event of an incorrect code, you can ask the user to provide a new code and create a new Challenge to check if it's correct. Alternatively, you can update the existing Challenge with a new AuthPayload value, but this approach is probably more complicated to implement. Type or paste the code sample for this step.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createChallenge() {
11
  const challenge = await client.verify.v2
12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .entities("ff483d1ff591898a9942916050d2ca3f")
14
    .challenges.create({
15
      authPayload: "123456",
16
      factorSid: "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
    });
18

19
  console.log(challenge.status);
20
}
21

22
createChallenge();

1
{
2
  "sid": "YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6
  "identity": "ff483d1ff591898a9942916050d2ca3f",
7
  "factor_sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8
  "date_created": "2015-07-30T20:00:00Z",
9
  "date_updated": "2015-07-30T20:00:00Z",
10
  "date_responded": "2015-07-30T20:00:00Z",
11
  "expiration_date": "2015-07-30T20:00:00Z",
12
  "status": "approved",
13
  "responded_reason": "none",
14
  "details": {
15
    "message": "Hi! Mr. John Doe, would you like to sign up?",
16
    "date": "2020-07-01T12:13:14Z",
17
    "fields": [
18
      {
19
        "label": "Action",
20
        "value": "Sign up in portal"
21
      }
22
    ]
23
  },
24
  "hidden_details": {
25
    "ip": "172.168.1.234"
26
  },
27
  "metadata": null,
28
  "factor_type": "totp",
29
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
30
  "links": {
31
    "notifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications"
32
  }
33
}

Now that you've verified your first user, we'd love your feedback on your experience and whether you plan to use Verify TOTP in production. We'd be happy to discuss your plans and offer suggestions. In addition, explore adding Verify's other verification channels beyond TOTP.

Let's build something amazing.