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. 

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


      		
      
        

      		
    

    

      
        

          
        

        
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 Message’s



To enable text-messages your app needs to be 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"
}

      		
    

    

      
        

          
        

        
Optional API’s

      		
      
        

      		
    

    

      
        

          
        

        
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/delete/:id?api_key={KEY}


EXAMPLE REQUEST:

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

{
  "message": "User was deleted.",
  "success":"true"
}

      		
    

    

      
        

          
        

        
Optional – Informational API’s

      		
      
        

      		
    

    

      
        

          
        

        
This API’s 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. 

  2. Plan:
    3. 

  3. SMS-enabled
    4. 




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"
}