Authy TOTP REST 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 a parameter

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

Production API locations

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

Demo AngularJS/NodeJS Implementation

You can clone and run our demo app repo. This full-stack implementation demonstrates both Authy TOTP and Phone Verification.

cURL API Examples

You can also clone our cURL API repo which implements all features of the Authy APIs including Authy's TOTP API. We've included a Postman collection and environment as well.

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, phone number 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.

Note: You need to store the unchanging authy_id against the user profile in your database or directory: You will use this ID every time you are verifying the user's token. For privacy reasons, your users can change their phone number registered with Authy without your knowledge by using the Authy mobile or desktop app or the Authy.com phone change security review. Their Authy ID may be used for other services as well.

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.

POST https://api.authy.com/protected/{FORMAT}/users/new?api_key={KEY}

Parameters

Name Type Description
send_install_link_via_sms Boolean (optional) Value to enable or disable the initial text message. Default=TRUE. Can be set from Dashboard.
user[email] String (required) More than one email can be stored per Authy ID, but only the initially created email will display in Dashboard until it is deleted.
user[cellphone] String (required) Foreign key for the AuthyID (which will be the primary key going forward).
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://api.authy.com/protected/json/users/new?api_key=d57d919d11e6b221c9bf6f7c882028f9" \
-d user[email]="user@domain.com" \
-d user[cellphone]="317-338-9302" \
-d user[country_code]="54"

Sample response

{
    "user": {
        "id":2
    }
}

Request with errors

curl "http://api.authy.com/protected/json/users/new?api_key=d57d919d11e6b221c9bf6f7c882028f9" \
-d user[email]="user.com" \
-d user[cellphone]="AAA-338-9302" \
-d user[country_code]="1"

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 you can override this behavior.

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}?api_key={KEY}

Parameters

Name Type Description
api_key String (required) The api key which can be obtained from the Authy dashboard.
action String (optional) The action or context we are trying to validate.
action_message String (optional) Message for the specific action.
force Boolean (optional) default=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://api.authy.com/protected/json/sms/46712?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://api.authy.com/protected/json/sms/1?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 sent even if the user is using the Authy App.

curl "http://api.authy.com/protected/json/sms/1?api_key=d57d919d11e6b221c9bf6f7c882028f&force=true"

Sample response

{
    "success":true,
    "message": "SMS token was sent"
}

Custom action example

curl "http://api.authy.com/protected/json/sms/1?api_key=d57d919d11e6b221c9bf6f7c882028f&action=change_preferences"

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

GET https://api.authy.com/protected/{FORMAT}/call/{AUTHY_ID}?api_key={KEY}

Parameters

Name Type Description
api_key String (required) The api key which can be obtained from the Authy dashboard.
action String (optional) The action or context we are trying to validate.
action_message String (optional) Message for the specific action.
force Boolean (optional) default=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://api.authy.com/protected/json/call/2?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://api.authy.com/protected/json/call/1?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 start even if the user is using the Authy App.

curl -i "http://api.authy.com/protected/json/call/1?api_key=d57d919d11e6b221c9bf6f7c882028f&force=true"

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 successfully logs in once using Authy this call will return 200 (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}?api_key={KEY}

Parameters

Name Type Description
token String The token you are verifying.
authy_id Integer the authy ID that was sent back when initially registering the user's device.
api_key String Your private API key.

Response

Name Type Description
token String Either "is valid" or "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://api.authy.com/protected/json/verify/1234567/1?api_key=d57d919d11e6b221c9bf6f7c882028f9"

Response

{
    "token": "is valid",
    "success": "true"
}

Invalid request

curl -i "http://api.authy.com/protected/json/verify/1234567/1?api_key=d57d919d11e6b221c9bf6f7c882028f9"

Response

{
    "success": "false",
    "errors": {
        "token":"is invalid"
    }
}

Forcing Validation

If the user has not finished registration, any token always works.

curl -i "http://api.authy.com/protected/json/verify/939393/3?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. Note, deleting a user will NOT immediately disable token verifications, as a 24 hour delay is typical before the user is permanently removed from the application. If you need to immediately disable a user and have not built this functionality into your user management system, the Authy dashboard "Delete user" function can be used, and after approving the email confirmation, 2FA for the user will be immediately disabled.

curl -X POST https://api.authy.com/protected/{FORMAT}/users/{USER ID}/delete -H "X-Authy-API-Key: {KEY}"

Parameters

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

Response

Name Type Description
success Boolean True if the user was scheduled for deletion.
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?api_key={KEY}

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 Boolean 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
GET https://api.authy.com/protected/{FORMAT}/app/details?api_key={KEY}

Parameters

Name Type Description
user_ip String (optional) IP of the user requesting to see the application details.

Response

Name Type Description
app App Object with information about the application.
success Boolean 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?api_key={KEY}

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 Boolean 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?api_key={KEY}

Parameters

Name Type Description

Response

Name Type Description
stats Array Array of Stats objects.
message String A message indicating the result of the operation.
success Boolean 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
}

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.

429: Too Many Requests API usage limit. If you reach API usage limits, a 429 will be returned. Please wait until you pass the limit and attempt the call again.

503: Service Unavailable There are multiple possible reasons for a HTTP 503 error.

  • An internal Authy error.

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

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.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.