Migrating from the Authy API to the Verify API for SMS 2FA

Migrating from the Authy API to the Verify API for SMS 2FA

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. As of November 2022, Twilio no longer provides support for Authy SMS/Voice-only customers. Customers who were also using Authy TOTP or Push prior to March 1, 2023 are still supported.

Some of the exciting features of the Verify API include:

• Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, and PHP
• Push authentication SDKs embeddable in your mobile app
• Programmable rate limits
• Improved visibility and insights

...and more!

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:

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].

Verify is also part of Twilio's CLI and new Open API specification. Check out our API Reference for examples and more information.

Migration examples

For code examples of migrating SMS 2FA from Authy to Verify, check out these code diffs:

• cURL
• Java
• C# / .NET
• Ruby
• Python
• PHP
• Node.js

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:

1. With the Verify API
2. In the Verify Console

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.

Error handling

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.

In Verify, verifications are started with E.164 format phone numbers like this: +15552317654. Check out the Lookup API for examples on how to transform national format numbers to E.164 format.

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:

1. The phone number in E.164 format. Required format for ongoing verification.
2. The country code in ISO 3166 alpha-2 format (e.g. US, CA, 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 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.

FAQ

What if we only stored the Authy ID and don't have the user's phone number?

We have an API for that! Learn more in the Export API documentation.

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?

Verify tokens are valid for 10 minutes and during that period the passcode will not change. To force a new passcode, complete the verification lifecycle or cancel the verification.

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.

Does Verify support TOTP?

Yes, learn more about implementing TOTP in the docs or try out TOTP with Twilio's CodeExchange.

Does Verify support Push?

Yes, Push support is in Pilot. Get in touch for access and more information.

Does Verify have a reporting API?

The Verify Attempts API is in Pilot and offers reporting capabilities. Get in touch to learn more.