The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience and new features. The Authy API will be maintained for the time being, but new development will be on the Verify API.
Some of the exciting features of the Verify API include:
- Push authentication SDKs embeddable in your mobile app
- Programmable rate limits
- Improved visibility and insights
This article applies to the Authy API. The Authy app is not going away. We are committed to growing, developing, and supporting the Twilio Authy app as a consumer application and as a complement to our work on the Verify API.
This guide provides an introduction to the Verify API and a set of guidelines to migrate your application from Authy to Verify.
Verify Base API
Verify is now hosted on Twilio's API. The new base URL is:
Use your Twilio credentials for Authentication
The Authy API required an Authy API Key. The Verify V2 API uses your Twilio Credentials found in the Console like in the following request:
curl -XPOST https://verify.twilio.com/v2/Services \ -d FriendlyName=MyServiceName \ -u '[YOUR ACCOUNT SID]:[YOUR AUTH TOKEN]'
Better developer tools including Twilio helper libraries
Unlike the Authy API, Twilio helper libraries support the Verify API. You no longer need the separate Authy helper libraries. We officially support libraries for C#, Java, PHP, Python, Ruby, Node.js, and Golang [Pilot].
For code examples of migrating SMS 2FA from Authy to Verify, check out these code diffs:
Applications are now Services
Verify uses Services for configuration. With the Authy API you created an Authy Application and used that API Key to manage verifications. In Verify you need both your Twilio Credentials and a Service SID. You can create and update a Service in two ways:
Legacy Applications were shared between Verify and Authy, so you may see an "application" in the Verify console. Services are the new method for configuration and you should be within the Services tab to get started with Verify V2.
Improved visibility and insights
Only available with our new Verify API, view the status of your verifications in the console including telephony delivery status.
Verify error codes are different from Authy error codes and can be found in the documentation. Common errors include:
- Error 60200 - Invalid parameter. For example, an invalid phone number.
- Error 60203 - Max send attempts reached. See the blog post on How to test Twilio Verify without getting rate limited.
Use E.164 formatted phone number instead of Authy ID
Authy IDs were used as the parameter to send SMS verifications with the Authy API.
Best practices for migration
Use Lookup to convert phone numbers to E.164 format
The free Lookup formatting API call will give you two pieces of useful information:
- The phone number in E.164 format. Required format for ongoing verification.
- The country code in ISO 3166 alpha-2 format (e.g.
BR, etc.). This is necessary to build an allow list or block list of countries.
Store both the E.164 formatted phone number and the country in your database for future use.
Learn more in the Lookup documentation.
Define allowed countries
If you have a global user base, you can allow all countries. If you are only expecting traffic from a handful of countries then you can create an allow list to help mitigate toll fraud. On the flipside, you can also create a block list if there are countries you do not expect traffic from.
Delete the Authy user from your application
After migrating a single user, we recommend removing the Authy user from the legacy application. You can find instructions on how to remove Authy Users in the documentation.
What if we only stored the Authy ID and don't have the user's phone number?
For privacy reasons, we're currently unable to return user phone numbers (users are able to change their phone number in the Authy app, which means we may have a different phone number than the number they originally provided when you registered the user).
Instead, we recommend prompting users to "confirm" their phone number during your migration process. To reduce friction, many customers offer a 30 day window to complete this confirmation step. You can fetch the last 4 digits of a user's phone number with the Authy User Status API endpoint for comparison.
At this point we recommend:
- Performing a Lookup on the inputted number. This allows you to check line type so you can, for example, set the channel preference for a landline number or throw an error and require a mobile number.
- Performing an initial phone verification. Using the Verify API, send a one-time passcode (OTP) to the phone number to ensure the user has possession.
- Once confirmed, adding the phone number to your database. You'll need the phone number to send future codes.
- Removing the Authy User. Delete the user from the Authy application to complete the migration process.
If users don't confirm their phone number within 30 days (or the window of your choice), you can deprecate Authy for them and have them re-enroll in 2FA.
If you need any assistance, please reach out and we can walk you through your options.
Why am I getting the same code with new verification requests using Verify?
Are rate limits different in Verify?
There are subtle differences in rate limits for Verify compared to Authy.
Rate limits for Verify SMS include:
- 5 send verification attempts within 10 minutes [more info].
- 5 check verification attempts [more info].
Please reach out to sales or support for more information on rate limits. Most customers find the default rate limits for Verify sufficient, but you can also protect your application with additional service rate limits.
How do I test Verify without getting rate limited?
See the blog post on How to test Twilio Verify without getting rate limited.
Will Verify support TOTP?
Yes, we plan to add TOTP support to Verify. Get in touch for release dates and more information.