Twilio Verify Best Practices

Phone verification is an important first step in your online relationship with a user. By verifying that a new registree on your website has the device they claim in his or her possession (and the provided number is accurate) you reduce spam and fraud while signaling your concern for the user's security.

Overseeing many integrations (and answering many questions), we've come up with a number of best practices and practical guidelines that can assist you while implementing phone verification. These best practices are also built into our Verify quickstart - we suggest running through it to see some implementation details. Further, Two-factor Authentication best practices have some overlap, especially for a complete registration and account security flow.

Plan A User Registration Flow

Phone verification or account verification is an important first step when signing up a user, but should be considered holistically in your application's registration and usage flow. Checking that a phone number is legitimate, associated with a device, and in the possession of a new registrant will cut down on spam sign-ups before you even grant a new user an account.

Suggested Account Verification, Security, and Usage Flow

Our currently suggested signup and usage flow is as follows (only proceed to the next step if the previous step is successful):

  1. Use Phone Verification (Account Verification) to determine if the user has the device they claim currently in possession.
  2. If your customer relationship will continue:
    1. Register the user for continuous Two-factor Authentication usage.
    2. Require Twilio Two-factor Authentications to protect any combination of log-ins, high-risk operations, and high-value transactions.

Explore the Customization Options

While Verify is a simple API, there are a few aspects you can customize.

Token Lengths

The Verify API allows you to set the length of the verification token delivered to the new user. You can set the token to between 4 and 10 digits to hit your desired combination of security and user convenience. The API defaults to a token length of 4, and if you are using the API for new account verification, there is little reason to go beyond this number. If however you are using the API for more frequent verification of a user, you might wish to increase token length to increase the possible amount of numbers any hacker needs to guess. 

The Verification Message

The vast majority of use cases don't require customization. By default, there is a single message template sent out through the SMS channel. The SMS message template contains your Application name from the Twilio Console. The English example is:

Your <App Name> verification code is: 1234

and the message is automatically localized and translated for your users based on their country code. You can override the language by sending in a locale parameter. The default code (for example, the '1234' above) is generated and validated through our service.

If you use the standard setup, you are only charged for carrier delivery charges and successful customer verifications.

Using Your Own One-Time Password

If you already have token validation and generation logic and would like to keep those systems in place, you can do so. We have a feature where you can submit your code to us and utilize our pre-screened message templates and localizations for both text and voice. Contact Twilio Sales and we'll help you enable this option.

Customizing the Verification Text

If those messages are insufficient, it is possible to change the verification message sent through the SMS and Voice channels. Contact Twilio Sales with a business case and we'll consider your request.

If you forego the built-in messaging, we will be unable to provide localization and translations for your verification messages. Additionally, our text-to-speech engine will limit delivery to fewer locales than our recorded messages (see our supported languages). If you customize the message in particular ways, you risk carriers flagging your messages as spam and not delivering them to your recipient.

Know the Limits and Timeouts

There are a few timeouts and limits (and design suggestions) to be aware of when building your Verify integration.

Token Validity Period

Once generated, tokens are valid for 10 minutes. We are unable to change the timout for token validity for your application. If your users make another request within the 10 minutes, they will receive the same token. You can poll to see the remaining valid time for a user's request.

Suggested Timing Between Verification Requests

To prevent abuse (and impatient users!), we suggest limiting verifications to 1 request per minute per phone number.

Twilio Request Latency

We don't guarantee API response times, but most Verify API requests will complete in under 500 milliseconds. With the 10 minute timeout, the majority of the delay you'll see during verification will be user input and not API requests.

Still Wondering About Phone Verification? We're Happy to Help.

Have additional questions about phone verification and our Verify API? We're very happy to talk best practices, design patterns, future-proofing and everything else that can help secure your app and cut your spam. Contact Twilio Sales and we'll help you optimize your unique Verify implementation.

 

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 browsing the Twilio tag on Stack Overflow.