Verification is an essential first step in your online relationship with a user. By verifying that a new user is who they say they are, you can reduce spam and fraud on your site while ensuring the user's security.
Designing user verification involves more than just picking the right verification channel. Twilio has supported thousands of customers rolling out verification and two-factor authentication (2FA) implementations. This guide will provide recommendations for each step of the user verification process, from collecting phone numbers to account recovery.
These recommendations are written with the Twilio Verify API in mind but many will apply regardless of your verification provider.
If you're ready to start building, check out one of our Verify Quickstarts, available in a variety of programming languages for a variety of verification channels.
Verification and authentication are similar user experiences but have a few key differences in how you can design the user experience.
Verification happens when you first associate details with a customer account. This could be:
Authentication, including two-factor authentication (2FA) or multi-factor authentication (MFA) happens during ongoing customer interactions like:
The Twilio Verify API can be used to both verify and authenticate user identities and can be used for all of these customer interactions.
Like every security solution, you want to make sure that the friction you're adding isn't going to prevent the user from achieving their goals, whether that's signing up for your service or completing a transaction.
The Twilio Verify API supports:
Each channel has different benefits. For example, SMS has the highest end user adoption while TOTP is more secure and works offline. You might ask if email-based 2FA is a good idea (better than no 2FA!).
Most companies support several verification channels and then let their users decide. For example, GitHub supports TOTP, SMS, and security keys and offers even more options for account recovery.
Read more about tradeoffs between the different authentication channels supported by the Verify API.
SMS offers less security than TOTP or push authentications, but in many cases you should still leave it available as an authentication option. SMS support is built into all mobile phones and—without a separate application—tokens delivered by SMS will make it to your users. The user experience benefits of SMS still make it a popular choice for many companies. Learn more about why SMS 2FA isn't going away.
If the choice is between password-only authentication or password plus SMS, adding SMS is a clear winner.
Push and Silent Device Approval authentications are the most secure channel for 2FA because they are tied to a specific device and resistant to phishing.
Push also offers the ability to deny an authentication request, which can be used to detect fraud. Push authentications are also very convenient for your users. Instead of having to open a mobile application and navigate to your website's token, push authentications present an "Approve"/"Deny" dialog within easy reach.
Silent Device Approval authentications simplify this process even further by happening silently in the background without any user involvement. Push and Silent Device Approval can be embedded directly into your application with our Verify Client Libraries (SDKs) so it doesn't require the user to download an additional app.
For an example user registration flow with one time passcodes, smart retry logic, and voice channel fallback, check out this Code Exchange project.
Allow customers to set authentication preferences and store those preferences for subsequent logins. This is a great way to delight your users and reduce frustrations during the authentication process. For example, landline users will want a voice call instead of an SMS. You could store preferences in your user database or use a third-party service like Segment Personas.
These channels can also be used for backup and account recovery (more on this below).
For phone or email verification use cases (as opposed to ongoing login or two-factor authentication), display the complete identifier in the interface so the user can detect any typos during the registration process. You can also introduce an intermediate step that asks the user to confirm the phone number before you send the OTP in order to catch mistakes.
<input>
element as a place to optimize the user experience. Learn more abouthow to design your HTML attributes to support autocomplete and more in this blog post.
To prevent abuse (and impatient users!) we always recommend building retry buffers into verification workflows. This helps prevent:
We suggest limiting verifications to 1 request / 30 seconds per phone number with exponential backoff. Learn more in the blog post about best practices for managing retry logic with SMS 2FA or check out this Code Exchange project with an example retry logic flow seen below.
_10Your <App Name> verification code is: 123456
Verify will automatically resolve the template's locale based on phone number country code or fallback to English. Using this automatic resolution is highly recommended. If you still must override locale for the verification, use the locale
parameter for any of our dozens of supported languages.
You can also provide a template to support use cases like do not share warnings, origin bound SMS codes, and your own verbiage.
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 use your own OTP and still use our pre-screened message templates and localizations for both text and voice. Contact Twilio Sales and we'll help you enable this option.
Once generated, tokens are valid for 10 minutes. We are unable to change the timeout for token validity for your application. If your users make another request within the 10 minutes, they will receive the same token.
Rate limits are in place to help prevent fraud and protect your application and Twilio's servers. For example, we limit send attempts to the same entity (phone number or email). Our built-in rate limits are sufficient for most customers, but you can also define your own rate limits. In addition, this blog post covers how to test and develop with the Verify API without getting rate limited.
With the 10 minute timeout, the majority of the delay you'll see during verification will be user input and not API requests.
Check out this document for more details about Twilio's REST API best practices and rate limits.
SMS messages sent with Programmable Messaging and Verify are priced per message segment.
Character limits for message segments depend on the types of characters used:
Character set | Character limit |
---|---|
Contains only GSM characters | 160 characters |
Contains Non-GSM characters (e.g. ó and ¡) | 70 characters |
When a message doesn't fit into one segment, it's automatically broken into two or more segments and you'll be billed for all of those segments. Therefore we recommend constructing your OTP messages to fit into one segment or be aware when it's going to take more than one. Use the segment calculator to confirm how many segments a message will result in.
The default, standard messages that Verify provides currently all fit within one message segment, except in the following circumstances:
pt
,
pt_BR
,
cs
,
el
true.
When
true
, if appending the privacy warning results in a message that takes more than one segment, then the privacy warning won't be appended.
true
In the case of these exceptions, your specific message may still fit within one message segment, depending on parameters that affect character length like friendly_name, code_length, locale, and other customization options that you select. You can check how many message segments your message will use with the Messaging Segment Calculator tool.
Monitor based on geography to detect spikes in unchecked verifications that could indicate abuse or delivery issues.
Get notified if something goes wrong or if abuse happens on your account with Twilio's usage triggers, available via the API, CLI, or Twilio Console.
Finally, leverage the Verify and Lookup error dictionary to handle errors appropriately in the customer application.
Now that you have all of the best practices, you can send an SMS OTP in less than 5 minutes with the Verify API with Twilio's Code Exchange. Learn more about the parameters supported in the API documentation or check out one of our quickstarts in the language of your choice. If you have questions about your implementation, please reach out. We can't wait to see what you build and secure!