Rate this page:

Verify TOTP Overview

Time-based one-time passcode (TOTP) is a strong authentication choice for users who can download a special app like Authy or Google Authenticator on their mobile device or computer. These authenticator apps generate unique numeric tokens with a standardized algorithm that uses the current time as an input. Some benefits of TOTP include:

  • More security: Tokens automatically expire and there are no one-time passwords (OTPs) for fraudsters to intercept, making it more secure than SMS, email, or voice channels.
  • Works offline: Generating and verifying a TOTP token does not require internet connectivity as long as a device’s time is synced.
  • No PII required: TOTP does not need a phone number to work, so no personally identifiable information (PII) is stored.

TOTP is a great choice for businesses looking for a more secure, private, and lower-cost user authentication option.

Graphic showing the relation between an OTP secret key, a user's phone, and an application's infrastructure

Start Building


See a demonstration of how to use Verify TOTP from Twilio’s Signal 2021 conference:


How are users handled?

A user is represented as an Entity within Verify TOTP. We advise using an immutable user identifier such as a system UUID, GUID, or SID for the identity property of an Entity so that no PII is stored. See Entity API for more details.

You can fetch an Entity by its identity property, but the control and storage of the identity relation with the user must be managed on your end.

The Factor API also does not store any kind of user information or PII.

How should a user with multiple factors on the same device be handled?

If a user has multiple TOTP factors on the same device, ensure that the factorSid of the intended factor is given when using the Challenge API to create a Verification Attempt.

As a best practice, we advise only allowing one TOTP factor (seed) per user at a time. When a user requests to generate a new seed, the old one should be deleted.

How do I change the Authy App logo for my Verify TOTP?

See this support article for more information on how to update the logo displayed in the Authy App for your TOTP.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!