Migrating from Authy to Verify 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. 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:

  • 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:

https://verify.twilio.com/v2/

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

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:

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.

Logs showing verification attempt statuses like pending, approved, and max attempts reached

Error handling

Verify error codes are different from Authy error codes and can be found in the documentation. Common errors include:

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

FAQ

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?

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.

Will Verify support TOTP?

Yes, we plan to add TOTP support to Verify. Get in touch for release dates and more information.

Does Verify have a reporting API?

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

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:

  • 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:

https://verify.twilio.com/v2/

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

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:

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.

Logs showing verification attempt statuses like pending, approved, and max attempts reached

Error handling

Verify error codes are different from Authy error codes and can be found in the documentation. Common errors include:

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

FAQ

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?

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.

Will Verify support TOTP?

Yes, we plan to add TOTP support to Verify. Get in touch for release dates and more information.

Does Verify have a reporting API?

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


Print Share Comment Cite Upload Translate
APA
Kelley Robinson | Sciencx (2024-03-29T06:07:18+00:00) » Migrating from Authy to Verify for SMS 2FA. Retrieved from https://www.scien.cx/2021/04/23/migrating-from-authy-to-verify-for-sms-2fa/.
MLA
" » Migrating from Authy to Verify for SMS 2FA." Kelley Robinson | Sciencx - Friday April 23, 2021, https://www.scien.cx/2021/04/23/migrating-from-authy-to-verify-for-sms-2fa/
HARVARD
Kelley Robinson | Sciencx Friday April 23, 2021 » Migrating from Authy to Verify for SMS 2FA., viewed 2024-03-29T06:07:18+00:00,<https://www.scien.cx/2021/04/23/migrating-from-authy-to-verify-for-sms-2fa/>
VANCOUVER
Kelley Robinson | Sciencx - » Migrating from Authy to Verify for SMS 2FA. [Internet]. [Accessed 2024-03-29T06:07:18+00:00]. Available from: https://www.scien.cx/2021/04/23/migrating-from-authy-to-verify-for-sms-2fa/
CHICAGO
" » Migrating from Authy to Verify for SMS 2FA." Kelley Robinson | Sciencx - Accessed 2024-03-29T06:07:18+00:00. https://www.scien.cx/2021/04/23/migrating-from-authy-to-verify-for-sms-2fa/
IEEE
" » Migrating from Authy to Verify for SMS 2FA." Kelley Robinson | Sciencx [Online]. Available: https://www.scien.cx/2021/04/23/migrating-from-authy-to-verify-for-sms-2fa/. [Accessed: 2024-03-29T06:07:18+00:00]
rf:citation
» Migrating from Authy to Verify for SMS 2FA | Kelley Robinson | Sciencx | https://www.scien.cx/2021/04/23/migrating-from-authy-to-verify-for-sms-2fa/ | 2024-03-29T06:07:18+00:00
https://github.com/addpipe/simple-recorderjs-demo