Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Authy API


(warning)

Warning

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. The Authy API is now closed to new customers and will be fully deprecated in the future.

For new development, we encourage you to use the Verify v2 API.

Existing customers will not be impacted at this time until Authy API has reached End of Life. For more information about migration, see Migrating from Authy to Verify for SMS(link takes you to an external page).

The Twilio Authy API makes it simple to add a second factor of authentication or passwordless logins to your web application. It supports OTP sent via voice and SMS, TOTP generated in the free Authy app(link takes you to an external page) (or any compatible authenticator app like Google Authenticator) and push authentication via the free Authy app(link takes you to an external page). To start working with the API, first create an application in the Console and get the API Key.


API Base URL

api-base-url page anchor

All URLs in the reference documentation use the following base URL:


_10
https://api.authy.com

All requests to the Authy REST API are served over HTTPS. Unencrypted HTTP is not supported.


All HTTP requests to the Authy REST API /protected endpoints are protected with an API Secret you pass as an HTTP header X-Authy-API-Key, e.g.:


_10
curl 'https://api.authy.com/protected/json/app/details' \
_10
-H "X-Authy-API-Key: $AUTHY_API_KEY"

The API Key can be found in the Authy section of the Twilio Console(link takes you to an external page) after clicking through to your Authy application.

Account security API Key.

Supported Formats

supported-formats page anchor

The Authy API currently supports JSON and XML formats. When making API calls, you will need to specify json or xml format.


This guide shows the three steps to completing a basic two-factor verification via SMS. Follow the links for more documentation on advanced features such as sending Push Authentications, registering users without needing their phone number or email, PSD2 compliance, and more.

First, create an Authy Application in the Twilio Console and grab the API Key as demonstrated above.

Step 1: Create an Authy User

step-1-create-an-authy-user page anchor

The AUTHY_ID from this step is necessary to send One-Time Passwords

Python
C#
Java
PHP
Ruby
curl

_17
# Download the helper library from https://github.com/twilio/authy-python
_17
from authy.api import AuthyApiClient
_17
_17
# Your API key from twilio.com/console/authy/applications
_17
# DANGER! This is insecure. See http://twil.io/secure
_17
authy_api = AuthyApiClient('api_key')
_17
_17
user = authy_api.users.create(
_17
email='new_user@email.com',
_17
phone='405-342-5699',
_17
country_code=57)
_17
_17
if user.ok():
_17
print user.id
_17
# user.id is the `authy_id` needed for future requests
_17
else:
_17
print user.errors()

Output

_10
{
_10
"message": "User created successfully.",
_10
"user": {
_10
"id": 123
_10
},
_10
"success": true
_10
}

An Authy Application is the set of common configurations used to create and check one-time passcodes and manage push authentications. This includes features like:

  • Application Name (used in the one-time password message templates)
  • Token Length
  • ...and more

One application can be used to send multiple tokens, it is not necessary to create a new application each time.

Authy Users documentation.

Step 2: Send an SMS with a One-Time Password

step-2-send-an-sms-with-a-one-time-password page anchor
Python
C#
Java
PHP
Ruby
curl

_11
# Download the helper library from https://github.com/twilio/authy-python
_11
from authy.api import AuthyApiClient
_11
_11
# Your API key from twilio.com/console/authy/applications
_11
# DANGER! This is insecure. See http://twil.io/secure
_11
authy_api = AuthyApiClient('api_key')
_11
_11
sms = authy_api.users.request_sms(authy_id)
_11
_11
if sms.ok():
_11
print sms.content

Output

_10
{
_10
"success":true,
_10
"message":"SMS token was sent",
_10
"cellphone":"+1-XXX-XXX-XX02"
_10
}

This will send a token to the end user through the specified channel. Supported channels are sms or call.

If the user has the Authy App, by default, the API will not send the 2FA code via SMS or voice. Instead, a push notification will go to the device, prompting the user to start their app to get the code. You can override this behavior.

One-time Password documentation.

Step 3: Verify the Token

step-3-verify-the-token page anchor
Python
C#
Java
PHP
Ruby
curl

_10
# Download the helper library from https://github.com/twilio/authy-python
_10
from authy.api import AuthyApiClient
_10
_10
# Your API key from twilio.com/console/authy/applications
_10
# DANGER! This is insecure. See http://twil.io/secure
_10
authy_api = AuthyApiClient('api_key')
_10
_10
verification = authy_api.tokens.verify(authy_id, token='1234567')
_10
print(verification.ok())

Output

_21
{
_21
"message": "Token is valid.",
_21
"token": "is valid",
_21
"success": "true",
_21
"device": {
_21
"city": "San Francisco",
_21
"country": "United States",
_21
"ip": "97.20.126.156",
_21
"region": "California",
_21
"registration_city": "San Francisco",
_21
"registration_country": "United States",
_21
"registration_device_id": 456456,
_21
"registration_ip": "97.34.234.11",
_21
"registration_method": "push",
_21
"registration_region": "California",
_21
"os_type": "android",
_21
"last_account_recovery_at": null,
_21
"id": 83372911,
_21
"registration_date": 1490996931
_21
}
_21
}

This will check whether the user-provided token is correct. The first time you verify a user you will need to force verification to complete the user registration process.

TokenSuccess in responseMessage in response
CorrecttrueToken is valid.
IncorrectfalseToken is invalid

One-time Password documentation.


We maintain helper libraries to abstract these API calls for all of our standard web languages.


Rate this page: