Authy API

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

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

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

The API Key can be found in the Authy section of the Twilio Console after clicking through to your Authy application.

Expand image

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.

1
# Download the helper library from https://github.com/twilio/authy-python
2
from authy.api import AuthyApiClient
3

4
# Your API key from twilio.com/console/authy/applications
5
# DANGER! This is insecure. See http://twil.io/secure
6
authy_api = AuthyApiClient('api_key')
7

8
user = authy_api.users.create(
9
    email='new_user@email.com',
10
    phone='405-342-5699',
11
    country_code=57)
12

13
if user.ok():
14
    print user.id
15
    # user.id is the `authy_id` needed for future requests
16
else:
17
	print user.errors()

1
{
2
  "message": "User created successfully.",
3
  "user": {
4
    "id": 123
5
  },
6
  "success": true
7
}

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.

1
# Download the helper library from https://github.com/twilio/authy-python
2
from authy.api import AuthyApiClient
3

4
# Your API key from twilio.com/console/authy/applications
5
# DANGER! This is insecure. See http://twil.io/secure
6
authy_api = AuthyApiClient('api_key')
7

8
sms = authy_api.users.request_sms(authy_id)
9

10
if sms.ok():
11
    print sms.content

1
{
2
    "success":true,
3
    "message":"SMS token was sent",
4
    "cellphone":"+1-XXX-XXX-XX02"
5
}

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.

1
# Download the helper library from https://github.com/twilio/authy-python
2
from authy.api import AuthyApiClient
3

4
# Your API key from twilio.com/console/authy/applications
5
# DANGER! This is insecure. See http://twil.io/secure
6
authy_api = AuthyApiClient('api_key')
7

8
verification = authy_api.tokens.verify(authy_id, token='1234567')
9
print(verification.ok())

1
{
2
  "message": "Token is valid.",
3
  "token": "is valid",
4
  "success": "true",
5
  "device": {
6
    "city": "San Francisco",
7
    "country": "United States",
8
    "ip": "97.20.126.156",
9
    "region": "California",
10
    "registration_city": "San Francisco",
11
    "registration_country": "United States",
12
    "registration_device_id": 456456,
13
    "registration_ip": "97.34.234.11",
14
    "registration_method": "push",
15
    "registration_region": "California",
16
    "os_type": "android",
17
    "last_account_recovery_at": null,
18
    "id": 83372911,
19
    "registration_date": 1490996931
20
  }
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.

One-time Password documentation.

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

• PHP Authy Helper Library
• Python Authy Helper Library
• Java Authy Helper Library
• Ruby Authy Helper Library