TOTP API

Authy uses a REST API. The API is designed to use HTTP response codes
to indicate status. The body of the response will also include more
information.

  • Both JSON and XML formats are supported by all API calls

  • You always need to specify a format (json | xml)

  • Any /protected/ api call requires you to pass an X-Authy-API-Key as an HTTP header

The api key can be obtained by logging into the Authy dashboard and selecting the app for which you are authenticating users

Return Codes

The following status codes are used:

200: OK
    Response is correct. The body of the response will include the data requested.

400: Bad Request
    There was an error with the request. The body of the response will have more info.

401: Unauthorized
    Token is invalid. If your API key is wrong a 401 will be generated. Please check the API key.

503: Service Unavailable
        There are multiple possible reasons for an HTTP 503 error.
  • An internal Authy error.

  • Your application is accessing an API call you don't have access to.

  • API usage limit. If you reach API usage limits, a 503 will be returned. Please wait until you pass the limit and reattempt the call.


Error codes

When the API returns a status other than 200, we add an error code in the message body. For further information, please check the error codes page for a complete list of possible errors.

Production API locations

Authy API server is at: https://api.authy.com

Sandbox API

Authy has a sandbox API at: http://sandbox-api.authy.com
The sandbox can be used for automated testing. Please contact your Authy representative for further information on using the sandbox.

Test hooks available on sandbox

1. Token Verification:
A HTTP 200 will always be served when /verify/{TOKEN} API is called, regardless of the value sent.

2. Device registration:
You may also register as many devices as needed on your tests, but please note the database is cleared on a periodic basis.

Please always contact your Authy representative when working with the sandbox for proper guideance.

Enabling two-factor authentication for a user

Before you can secure a user's login you need to create an Authy user. Authy requires you send an email, cellphone and country code for each Authy user. In response you get an Authy ID which you must then store with your user's profile in your own application.

A user can have multiple e-mails but only one cellphone. Two separate api calls to register a user with the same cellphone and different e-mails will return the same authy_id and store both emails for that Authy user.

NOTE: You need to store the authy_id against the user profile in your database or directory: You will use this id everytime you are verifying the user's token.

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

Parameters

Name Type Description
send_install_link_via_sms Boolean Optional. Boolean (true or false) value to enable or disable the initial text message. This is enabled by default.
user[email] String Required.
user[cellphone] String Required. Primary key for the user.
user[country_code] String Required. Numeric calling country code of the country Eg: 1 for the US. 91 for India. 54 for Mexico. See: Country code list dropdown

Response

Name Type Description
user User Fields related to the created user.

Example

NOTE: You can use dashes, periods, spaces or nothing to separate parts of the cell phone number.

curl "http://sandbox-api.authy.com/protected/json/users/new" \
-d user[email]="[email protected]" \
-d user[cellphone]="317-338-9302" \
-d user[country_code]="54" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response

{
    "user": {
        "id":2
    }
}
Request with errors

curl "http://sandbox-api.authy.com/protected/json/users/new" \
-d user[email]="user.com" \
-d user[cellphone]="AAA-338-9302" \
-d user[country_code]="1" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response

{
    "errors": {
        "email":"is invalid",
        "cellphone":"must be a valid cellphone number."
    }
}

Requesting SMS codes

Once an Authy ID has been generated for a user, you can provide a two-factor stage to a login. If the user downloads and installs the Authy smartphone application, it will generate the codes required. However, for users that don't own a smartphone, Authy allows you to use text messages to send the one time passcode. By default this call will be ignored if the user has downloaded and registered the Authy smartphone application against their phone number. However this behaviour can be over-ridden.

Custom Actions
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 have to pass the same action when verifying the code.

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

Parameters

Name Type Description
action String Optional. The action or context we are trying to validate.
action_message String Optional. Message for the specific action.
force Boolean Optional, defaults to false. When true it sends the message even if the user is using the mobile app. You can configure the default behaviour using your Authy Dashboard account.

Response

Name Type Description
success Boolean Returns true if the request was successful.
message String A message indicating what happened with the request.
cellphone String The phone number used to send the message.
ignored Boolean True if the request was ignored.
device String The name of the most recent device used by the user. This is only returned when the SMS was ignored.

Example

Sending a code via SMS
curl -i "http://sandbox-api.authy.com/protected/json/sms/46712" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "success":true,
    "message":"SMS token was sent",
    "cellphone":"+1-XXX-XXX-XX02"
}
Text message send request on a user using the Authy app

curl -i "http://sandbox-api.authy.com/protected/json/sms/1" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "message":"Ignored: SMS is not needed for smartphones. Pass force=true if you want to actually send it anyway.",
    "cellphone":"+1-XXX-XXX-XX02",
    "device":"android",
    "ignored":true,
    "success":true
}
You can pass in a force=true parameter to this api. This will force
the SMS to be send even if the user is using the Authy App.

curl "http://sandbox-api.authy.com/protected/json/sms/1&force=true" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "success":true,
    "message": "SMS token was sent"
}
Custom action example

curl "http://sandbox-api.authy.com/protected/json/sms/1&action=change_preferences" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "success":true,
    "message":"SMS token was sent"
}

Phone Call Tokens

For users that don't own a smartphone, and are having trouble with SMS Tokens,
Authy allows you to use phone calls instead.

This call will be ignored if the user is using the Authy Mobile

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

Parameters

Name Type Description
action String The action or context we are trying to validate.
action_message String Optional message for the specific action.
force Boolean Defaults to false. When true it sends the message even if the user is using the mobile app. You can configure the default behaviour using your Authy Dashboard account.

Response

Name Type Description
success Boolean Returns true if the request was successful.
message String A message indicating what happened with the request.
cellphone String The phone number used to send the message.
ignored Boolean True if the request was ignored.
device String The name of the most recent device used by the user. This is only returned when the SMS was ignored.

Example

Requesting a code via Phone Call

curl -i "http://sandbox-api.authy.com/protected/json/call/2" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "success":true,
    "message":"Call started...",
    "cellphone":"+1-XXX-XXX-XX02"
}
Phone call request on a user using the Authy app
curl -i "http://sandbox-api.authy.com/protected/json/call/1" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "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.",
    "cellphone":"+1-XXX-XXX-XX02",
    "device":"android",
    "ignored":true,
    "success":true
}
You can pass force=true as parameter to this api. This will force
the PHONE CALL to started even if the user is using the Authy App.

curl -i "http://sandbox-api.authy.com/protected/json/call/1&force=true" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
    "success": true,
    "message":"Call started."
}

Verifying a token

To verify a token simply pass in the token that the user entered and the authy id of the user (which should have stored in your database when you registered the user above). Authy will use HTTP status codes for the response.

To prevent user from being locked out, until the user succesfully logins once using Authy this call will return 200 or valid token
If you wish to verify token regardless, see below to see how to force verification.
HTTP 200 means valid token and HTTP 401 means invalid token

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

Parameters

Name Type Description
token String the token you are verifying
authy_id Integer the authy id that was sent back when registering the users device

Response

Name Type Description
token String it returns "is valid" if the code was valid or "is invalid" if the token is invalid.
success String "true" if the code was valid. Please note this field is a String and not a Boolean.

Example

Valid request
curl -i "http://sandbox-api.authy.com/protected/json/verify/0000000/1" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Response
{
    "token": "is valid",
    "success": "true"
}
Invalid request
curl -i "http://sandbox-api.authy.com/protected/json/verify/1234567/1" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Response
{
    "success": "false",
    "errors": {
        "token":"is invalid"
    }
}
Forcing Validation
if user has not finished registration any token always works.
curl -i "http://sandbox-api.authy.com/protected/json/verify/939393/3" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Response
{
    "token":"Not checked. User has not yet finished the registration process. Pass force=true to this API to check regardless (more secure)."
}
Forced verification on unregistered user
{
    "errors": {
        "token":"is invalid"
    }
}
Custom Actions
When using custom actions to send SMS you have to pass action= to validate the code.
For more information see Custom Actions under the SMS Tokens sections.

{
    "token": "is valid"
}

Deleting User

If you want to remove users from your application you can use the delete API.

POST https://api.authy.com/protected/{FORMAT}/users/{USER ID}/delete

Parameters

Name Type Description
user_ip String The ip requesting to delete the user

Response

Name Type Description
success Bool True if the user was deleted.
message String A messaging indicating the result of the operation.

Example

{
    "message": "User was added to remove.",
    "success": true
}

Register User Activities

Optionally you can register some of the activities that your user do on your application. This helps us to identify fraudulent behaviours.
For example if you register that a user reset his password and then he tries to change his phone with Authy we can know that something weird is happening.

Allowed types:

          password_reset
          banned
          unbanned
          cookie_login

POST https://api.authy.com/protected/{FORMAT}/users/{USER ID}/register_activity

Parameters

Name Type Description
data Hash Hash of data that you want to associate with this activity.
type String Activity type. See below for more details.
user_ip String IP of the user that is doing the request. Both IPv4 and IPv6 are supported.

Response

Name Type Description
message String A message indicating the result of the operation.
success Bool True if the result was successful.

Example

{
    "message": "Activity was created."
}

Application Details

This call will retrieve the application details such as:

1. Name:
2. Plan:
3. SMS-enabled

You can use this call to know if the App has or not SMS enabled.

GET https://api.authy.com/protected/{FORMAT}/app/details

Parameters

Name Type Description
user_ip String IP of the user requesting to see the application details. Optional.

Response

Name Type Description
app App Object with information about the application.
success Bool True if the request was successful.
message String A message indicating the result of the operation.

Example

{
    "app": {
        "name":"Authy Docs",
        "plan":"sandbox",
        "sms_enabled":false,
        "white_label":false
    },
    "message":"Application information.",
    "success":true
}

User Status

This call will retrieve user details such as:

1. country_code
2. phone number: last 4 digits of phone number.
3. devices: List of devices, options are: android, android_tablet, ios, authy_chrome, sms
4. registered: true when the Authy Mobile/Desktop App was registered.
5. confirmed: true when the user has used a valid code before.


GET http://api.authy.com/protected/{FORMAT}/users/{USER ID}/status

Parameters

Name Type Description
user_ip String IP of the user requesting to see the application details. Optional.

Response

Name Type Description
status Dictionary Status contains information about the user.
message String A message indicating the result of the operation.
success Bool True if the request was successful.

Example

{
    "status": {
        "authy_id":2,
        "confirmed":true,
        "registered":true,
        "country_code":1,
        "phone_number":"XXX-XXX-9302",
        "devices": [
            "authy_chrome",
            "android"
        ]
    },
    "message":"User status.",
    "success":true
}

Application Stats

This call will retrieve the application stats by month in an Array.
You can use this call to know App Quotas.

GET https://api.authy.com/protected/{FORMAT}/app/stats

Parameters

Name Type Description
user_ip String IP of the user requesting to see the application details. Optional.

Response

Name Type Description
stats Array Array of Stats objects.
message String A message indicating the result of the operation.
success Bool True if the request was successful.

Example

{
    "stats": [
        {"sms_count":0,"users_count":0,"month":"January","year":2013},
        {"sms_count":0,"users_count":0,"month":"October","year":2012},
        {"sms_count":0,"users_count":1,"month":"November","year":2012}
    ],
    "message":"Monthly statistics.","success":true
}