Authy One-Time Passwords (OTP)

When you call the API to start either an SMS or voice-based authentication, it automatically checks to see if that user has previously downloaded the Authy app or has an app installed that uses our SDK. 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.

If a user has no record of installing a device, then the API will continue to send the code via SMS or voice. You can override the default behavior to force the sending of code via SMS or voice every time. This is a useful override if a user is specifically selecting "Send SMS" or "Get code via voice call" in your application UI.

For information on timing and other constraints like rate limiting, see our two-factor authentication best practices.

GET https://api.authy.com/protected/{FORMAT}/sms/{AUTHY_ID}

Supported languages are: Afrikaans (af), Arabic (ar), Catalan (ca), Chinese (zh), Chinese (Mandarin) (zh-CN), Chinese (Cantonese) (zh-HK), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Finnish (fi), French (fr), German (de), Greek (el), Hebrew (he), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Malay (ms), Norwegian (nb), Polish (pl), Portuguese - Brazil (pt-BR), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Tagalog (tl), Thai (th), Turkish (tr), Vietnamese (vi). We support the format country-region as described in IETF's BPC 47. If no region is given (or supported), there will be a default by country.

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. The user's notification will look like this:

Expand image

If the user has the Authy app installed the API response will look like this:

1
{
2
    "message":"Ignored: SMS is not needed for smartphones. Pass force=true if you want to actually send it anyway.",
3
    "cellphone":"+1-XXX-XXX-XX02",
4
    "device":"android",
5
    "ignored":true,
6
    "success":true
7
}

You can override this behavior and force sending an SMS or Voice call. This is a useful override if a user is specifically selecting "Send SMS" or "Get code via voice call" in your application UI.

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, {'force': True})
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
}

Optionally, you can limit a specific token to a single action, for example coupling a one-time password to a specific login request or transaction. Most implementations will not need this feature.

You can pass action= and action_message= (optional) to send a code that is only valid for the given action. This is useful if you require codes to perform different actions on your app, for example, you can pass action=login&action_message="Login code"when sending a login code.

When using this option you must pass the same action when verifying the code.

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(
9
    authy_id, 
10
    {'action': 'login', 'action_message': 'Login code'})
11

12
if sms.ok():
13
    print sms.content

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

For users that don't own a smartphone or are having trouble with SMS Tokens, Authy allows you to use phone calls instead. Like SMS, by default this call will be ignored if the user is using the Authy Mobile app. You can override the default behavior with the force parameter.

GET https://api.authy.com/protected/{FORMAT}/call/{AUTHY_ID}

If the user has the Authy App, by default, the API will not call the user. See above for more details. The API response will look like this:

1
{
2
  "message": "Call ignored. User is using  App Tokens and this call is not necessary. Pass force=true if you still want to call users that are using the App.",
3
  "cellphone": "+1-XXX-XXX-XX02",
4
  "device": "android",
5
  "ignored": true,
6
  "success": true
7
}

Like SMS, you can pass force=true as a parameter to this API. This will force the phone call to start even if the user is using the Authy app.

To verify a one-time password pass in the user provided token and the user authy_id. Twilio will use HTTP status codes for the response.

GET https://api.authy.com/protected/{FORMAT}/verify/{TOKEN}/{AUTHY_ID}

*Note: Until you successfully verify a token for a new user, this call will return 200.

When the TOTP token is generated in the Authy app or in the SDK, additional device information and registration data are provided in the response.

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
}

The same API is used to verify tokens from TOTP, sms, and voice channels. However when the OTP token is delivered via SMS or voice call, no additional device details are provided and the response will look like:

1
{
2
  "message": "Token is valid.",
3
  "token": "is valid",
4
  "success": "true",
5
  "device": {
6
    "id": null,
7
    "os_type": "sms",
8
    "registration_date": 1490996931,
9
    "registration_method": null,
10
    "registration_country": null,
11
    "registration_region": null,
12
    "registration_city": null,
13
    "country": null,
14
    "region": null,
15
    "city": null,
16
    "ip": null,
17
    "last_account_recovery_at": null,
18
    "last_sync_date": null
19
  }
20
}

Use force=true to force verification of a one-time password from a new user.

1
curl -i "http://api.authy.com/protected/json/verify/{TOKEN}/{AUTHY_ID}" \
2
  -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"

When using custom actions to send SMS you have to pass action= to validate the one-time password.
For more information see Custom Actions.

1
{
2
  "token": "is valid"
3
}

A verification attempt with an invalid token will return a 401 Unauthorized with the following Response body:

1
{
2
  "message": "Token is invalid",
3
  "token": "is invalid",
4
  "success": false,
5
  "errors": {
6
    "message": "Token is invalid"
7
  },
8
  "error_code": "60020"
9
}

When you enroll a user, they will automatically be able to generate Soft Token TOTP codes in the Authy App if they register for Authy with the same phone number that you used to enroll them. You do not need to do anything additional to take advantage of the Authy app. You can disable this behavior with the 'Sync tokens in Authy app' setting in the Authy settings in the Twilio Console.

To validate these One-Time Passwords, see Verify a One-Time Password below.

To support other Authenticator apps, like Google Authenticator, display a QR code to your users that contain a compatible OTP secret. The API will return a link to a valid QR code.

To customize the QR label and give the final user context about the token like account name or email, you can include the label param in the QR generation endpoint. That way many Authenticator apps will automatically render the label in the token list.

To enable, browse to your Authy application in the Twilio Console. Click on your App's Settings and scroll to the bottom.

Note: each QR code request will generate a unique TOTP seed. You can only have a single active QR code per user per protected site. Requesting an additional QR code for a user will invalidate the previous secret and generate a new QR code.

When providing a QR code to a user, be sure to have them validate the code before applying 2FA protection to their account.

POST https://api.authy.com/protected/{FORMAT}/users/{AUTHY_ID}/secret