Jump To …

Authy Api Documentation

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.

The following status codes are used:

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

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

HTTP 401: Unauthorized
  Token is invalid. If your API key is wrong a 401 will also be served,
  so check the response body, it might be that the API_KEY is invalid.

HTTP 503: Service Unavailable
  Many reasons, body will include details
  - An internal error on Authy.
  - Your application is accessing an API call you don't have access too.
  - API usage limit. If you reach API usage limits a 503 will be returned,
  please wait until you can do the call again.
  • 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 api_key as
    a parameter

Production and Test API locations

Production API

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

Sandbox API (great for automated testing)

Authy has a sandbox API at: http://sandbox-api.authy.com

You can use this sandbox to test your implementation easily.

Test hooks available on sandbox

  1. Token Verification:
    If token is “0000000” a HTTP 200 will always be served when /verify/{TOKEN} API is called, regardless of the id.

  2. Device registration:
    You may also register as many devices as needed on your tests. This database is cleared periodically

Super Quick Reference

There are only 2 required API calls:

1. Enabling two-factor on a user:

format: json | xml. (required)
user[email]: Required.
user[cellphone]: Required. Used by the API to match the user. user[country_code]: Required. Numeric calling country code of the country.

Eg: 1 for the US. 91 for India. 54 for Mexico.
See: Country code list dropdown
api_key: required. This is the your private API key.

NOTE: 2 api calls with the same cellphone and different e-mails will return the same authy_id. We match users based on cellphone number only.

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

2. Verifying a user token:

format: json | xml
token: the token you are verifying
authy_id: the authy id that was sent back when registering the users device
api_key: Your private API key

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

Enabling two-factor on a user

When the user wants to enable two-factor authentication you need to create a new Authy user.
To create a user you need to send authy api his e-mail, cellphone and his country_code. A user can have multiple e-mails but only 1 cellphone ( we use the cellphone to match the user).

We do not match the user using his e-mail, so a user can have multiple e-mails with same cellphone. Given the same cellphone Authy will always return the same authy_id back.

You need to store the authy_id in your database: You will use this id everytime you are verifying the user’s token.

DEFINITION:

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

International numbers are supported by sending their country codes.

NOTE: You can use dashes, periods, spaces or nothing to separate number.

EXAMPLE REQUEST:

curl "http://sandbox-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"


EXAMPLE RESPONSE:

{
  "user":
  {
    "id":1
  }
}


EXAMPLE REQUEST WITH COUNTRY CODE:

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

EXAMPLE RESPONSE:

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


EXAMPLE REQUEST WITH ERRORS:

curl "http://sandbox-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"

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

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

DEFINITION:

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

FORCE TOKEN VERIFICATION:

https://api.authy.com/protected/{FORMAT}/verify/{TOKEN}/{AUTHY_ID}?api_key={KEY}&force=true

Valid Token

HTTP CODE: 200

EXAMPLE VALID TOKEN REQUEST:

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

EXAMPLE VALID TOKEN RESPONSE:

HTTP/1.1 200 OK
Content-Type: text/html
Date: Tue, 17 Jan 2012 01:22:13 GMT
Server: thin 1.2.11 codename Bat-Shit Crazy
X-Frame-Options: sameorigin
X-Xss-Protection: 1; mode=block
Content-Length: 11
Connection: keep-alive

{ 
  "token": "is valid" 
}

Invalid Token

HTTP CODE: 401

EXAMPLE INVALID TOKEN REQUEST:

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

EXAMPLE INVALID TOKEN RESPONSE:

HTTP/1.1 401 Unauthorized
Content-Type: text/html
Date: Tue, 17 Jan 2012 01:25:43 GMT
Server: thin 1.2.11 codename Bat-Shit Crazy
X-Frame-Options: sameorigin
X-Xss-Protection: 1; mode=block
Content-Length: 13
Connection: keep-alive


{
  "errors":
  {
    "token":"is invalid"
  }
}

Forcing Validation

If user has not finished registration any token always works.

EXAMPLE VERIFICATION ON NOT YET REGISTERED USER

curl -i "http://sandbox-api.authy.com/protected/json/verify/939393/3?api_key=d57d919d11e6b221c9bf6f7c882028f9"

HTTP/1.1 200 OK
Server: nginx/1.0.14
Date: Tue, 26 Jun 2012 22:39:35 GMT
Content-Type: application/json;charset=utf-8
Connection: keep-alive
Status: 200 OK
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
Content-Length: 139

{
  "token":"Not checked. User has not yet finished the registration process. Pass force=true to this API to check regardless (more secure)."
} 


EXAMPLE FORCED VERIFICATION ON UNREGISTERED USER

curl -i "http://sandbox-api.authy.com/protected/json/verify/939393/3?api_key=d57d919d11e6b221c9bf6f7c882028f9&force=true"
HTTP/1.1 401 Unauthorized
Server: nginx/1.0.14
Date: Tue, 26 Jun 2012 22:43:48 GMT
Content-Type: application/json;charset=utf-8
Connection: keep-alive
Status: 401 Unauthorized
X-Frame-Options: sameorigin
X-XSS-Protection: 1; mode=block
WWW-Authenticate: Basic realm="Access Denied"
Content-Length: 33

{
  "errors":
  {
  "token":"is invalid"
  }
}

SMS Tokens.

Text Messages

Text-messages are available on app on the Starter plan(free) or higher.

For users that don’t own a smartphone, Authy allows you to use text messages.

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

DEFINITION:

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

EXAMPLE SMS SEND REQUEST:

curl -i "http://sandbox-api.authy.com/protected/json/sms/2?api_key=d57d919d11e6b221c9bf6f7c882028f9"

EXAMPLE SMS SEND RESPONSE:

HTTP/1.1 200 OK

{
  "success":"SMS token was sent"
}


EXAMPLE SMS SEND REQUEST ON A USER USING AUTHY APP:

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


HTTP/1.1 200 OK

EXAMPLE SMS REQUEST ON USER USING AN AUTHY APP
{
  "ignored":"SMS is not needed for smartphones. Pass force=true if you want to actually send it anyway."
}

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.

EXAMPLE FORCED SMS SEND REQUEST:

curl -i "http://sandbox-api.authy.com/protected/json/sms/1?api_key=d57d919d11e6b221c9bf6f7c882028f&force=true"
EXAMPLE FORCED SMS SEND RESPONSE:

HTTP/1.1 200 OK

{
  "success":"SMS token was sent"
}

You can pass shortcode=true parameter to send the message using short codes. This feature is only supported for U.S and Canada.

EXAMPLE USING SHORT CODES.

curl -i "http://sandbox-api.authy.com/protected/json/sms/1?api_key=d57d919d11e6b221c9bf6f7c882028f&force=true&shortcode=true"
EXAMPLE FORCED SMS SEND RESPONSE:

HTTP/1.1 200 OK

{
  "success":"SMS token was sent"
}

Phone Call Tokens.

Phone Calls

To enable phone calls, your app needs to be on the Starter plan(free) or higher.
You also need to contact us at support@authy.com.

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

DEFINITION:

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

EXAMPLE PHONE CALL REQUEST:

curl -i "http://sandbox-api.authy.com/protected/json/call/2?api_key=d57d919d11e6b221c9bf6f7c882028f9"

EXAMPLE PHONE CALL RESPONSE:

HTTP/1.1 200 OK

{
  "success": true, "message":"Call started."
}


EXAMPLE PHONE CALL REQUEST ON A USER USING AUTHY APP:

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


HTTP/1.1 200 OK

EXAMPLE PHONE CALL REQUEST ON USER USING AN AUTHY APP
{
  "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."
}

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.

EXAMPLE FORCED PHONE CALL REQUEST:

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

EXAMPLE FORCED PHONE CALL RESPONSE:

HTTP/1.1 200 OK

{
  "success": true, "message":"Call started."
}

Optional APIs

Deleting User

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

DEFINITION:

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


EXAMPLE REQUEST:

curl -X POST "http://sandbox-api.authy.com/protected/json/users/2/delete?api_key=d57d919d11e6b221c9bf6f7c882028f9"

{
  "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.

Params:

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

Allowed types:

  password_reset
  banned
  unbanned
  cookie_login
DEFINITION

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

EXAMPLE REQUEST:

curl "http://sandbox-api.authy.com/protected/json/users/2/register_activity?api_key=d57d919d11e6b221c9bf6f7c882028f9" \
-d data[reason]="Too many login attempts." \
-d data[attempts_count]=2500 \
-d type="banned" \
-d ip="86.112.56.34"


EXAMPLE RESPONSE:

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

Informational APIs

This APIs are only for those writing plugins for services like Wordpress or informational Dashboards. They provide information about the applications.

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.

DEFINITION:

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


EXAMPLE REQUEST:

curl "http://sandbox-api.authy.com/protected/json/app/details?api_key=d57d919d11e6b221c9bf6f7c882028f9"

{
  "app":
  {
    "name":"Authy Docs",
    "plan":"sandbox",
    "sms_enabled":false,
    "white_label":false
  },
  "message":"Application information.",
  "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.

DEFINITION:

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


EXAMPLE REQUEST:

curl "http://sandbox-api.authy.com/protected/json/app/stats?api_key=d57d919d11e6b221c9bf6f7c882028f9"
{
  "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
}