OneTouch API

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

Return Codes

The following are the return HTTP codes supported by the Dashboard API.

200: Response is correct.
              The body of the response will include the data requested.
400: There was an error with the request.
              The body of the response will have more information.
401: API Key is invalid.
              Please check your api key.
404: The requested resource was not found.
              If the device uuid you are sending is not associated to a device,
              or you are trying to access to a non owned device you may get this error.
503: Many reasons, body will include details:
              An internal error on Authy OneTouch.
              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.

Supported Formats

At the moment we support JSON and XML formats.
For convenience and compatibility with old http implementations we only support the POST and GET http verbs.
You always need to specify a format (json | xml),

Production API locations

API is located at: https://api.authy.com

Verifying authenticity of callbacks from Authy

This is an optional step but will improve the overall security of your implementation. Authy uses a HTTP HMAC signature on the callback to your server so that you can verify the authenticity. The signature will be on the HTTP headers as X-Authy-Signature. If you configured a callback url to receive notifications when a user approves/denies a transaction with Authy OneTouch, you should verify the request authenticity.

To verify the callback follow these steps:

1. Create a string using the url without params:

url = request.url
#=> "https://yoursite.com/onetouch/callback"
2. Create a string variable with the HTTP method in upper case (GET, POST):

http_method = request.method
#=> "POST"
3. Sort the list of received parameters in case-sensitive order and convert them to URL format (both key and value should be URL-encoded):

params = request.params
#=> {b: "val|ue&2", a: "value1"}
sorted_params = params.to_param
#=> "a=value1&b=val%7Cue%262"
4. Get the nonce from the http header:

nonce = request.headers["X-Authy-Signature-Nonce"]
#=> 1427849783.886085
5. Join nonce, http_method, url and sorted_params together with the | character:
      NOTE: The string should contain exactly 3 | characters.

data = nonce + "|" + http_method + "|" + url + "|" + sorted_params
#=> "1427849783.886085|POST|https://yoursite.com/onetouch/callback|a=value1&b=val%7Cue%262"
6. Hash the resulting data using HMAC-SHA256, using your api key as the key:

digest = hmac_sha256(data, api_key)
5. Encode in base64 the digest:

digest_in_base64 = encode_in_base64(digest)
7. Encode in base64 the digest. Base64 encoding should not contain line feeds. It must be encoded as described in the RFC 4648 (https://tools.ietf.org/html/rfc4648):

digest_in_base64 = encode_in_base64(digest)
8. Compare the digest_in_base64 with the http header X-Authy-Signature.

request.headers["X-Authy-Signature"] == digest_in_base64
#=> if true, signature is ok!

Quick overview

Authy OneTouch uses a very simple API consisting of two endpoints. One for creating approval requests and another to check the status of the approval request. To simplify the process of handling a request, you can set a callback URL in the Authy dashboard. When a user responds to the OneTouch notification, the Authy API posts data to your callback URL. If you are unable to provide a URL or you would like to simply poll Authy for the status of a request, you can call the ApprovalRequest endpoint.

Create ApprovalRequest

This is the main endpoint. This will create a new approval request for the given Authy ID and send it to the end user along with a push notification to the Authy smartphone application.

If you configured a callback url and the user responds to the notification, the Authy service will make a HTTP request to it with the transaction response.

POST https://api.authy.com/onetouch/{FORMAT}/users/2/approval_requests

Parameters

Name Type Description
message String Required. The message shown to the user when the approval request arrives.
details Hash Dictionary containing the [ApprovalRequest] details that will be shown to user
hidden_details Hash Dictionary containing the approval request details hidden to user.
logos Hash Dictionary containing the logos that will be shown to user.
seconds_to_expire Integer Optional, defaults to 86400 (one day). Number of seconds that the approval request will be available for being responded. If set to 0, the approval request won't expire. Expiration time can be set to several months, without affecting security. For certain use cases, it might be important to set a short expiration time. However, expiration time should not affect security by enforcing users to act too quickly. Instead, the users should be able to take their time to check the details of the approval requests before approving/denying it.

Response

Name Type Description
approval_request Hash Hash containing the UUID of the created approval request.

Example

Creating a new approval request

curl "http://api.authy.com/onetouch/json/users/2/approval_requests" \
-d message="Login requested for a CapTrade Bank account." \
-d details[username]="Bill Smith" \
-d details[location]="California, USA" \
-d details[Account Number]="981266321" \
-d hidden_details[ip_address]='10.10.3.203' \
-d seconds_to_expire=120 \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response
{
  "approval_request":{
    "uuid":"550e8400-e29b-41d4-a716-446655440000"
  },
  "success":true
}
Using a custom logo

By default, all the approval requests createed will be shown to the user using the logo defined in your Authy application in the Authy dashboard. However you can provide a customized logo at the time of the request. This is useful if you require an image that is specific to the action.

The logos parameter is expected to be an array of objects, each object with two fields: res (for resolution) and url (the location where you host your logo). If you include the logos parameter, we expect it to include a res with value default. If you don't include it, an error will be returned.

The other options for the res field on the logo are:

  • default (if you don't provide logos for each resolution this will be used instead)

  • low (will be shown on devices with low resolution)

  • med (will be shown on devices with medium resolution)

  • high (will be shown on devices with high resolution)

Creating a new approval request with custom logos.

curl "http://api.authy.com/onetouch/json/users/2/approval_requests" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
-d message="Login requested for a CapTrade Bank account." \
-d details[username]="Bill Smith" \
-d details[location]="California, USA" \
-d details[Account Number]="981266321" \
-d hidden_details[ip_address]='10.10.3.203' \
-d seconds_to_expire=120
-d logos[][res]='default' \
-d logos[][url]='http://example.com/logos/default.png' \
-d logos[][res]='low' \
-d logos[][url]='http://example.com/logos/low.png'
Sample response

{
  "approval_request": {
    "uuid":"550e8400-e29b-41d4-a716-446655440000"
  },
  "success":true
}

Check ApprovalRequest status

This call returns the status of the given approval request. This end point doesn't require to sign the request.

GET https://api.authy.com/onetouch/{FORMAT}/approval_requests/:uuid

Parameters

Name Type Description
uuid String Required. The approval request ID. (Obtained from the response to an ApprovalRequest)

Response

Name Type Description
approval_request Hash Hash containing the status of the approval request.

Example

curl "http://api.authy.com/onetouch/json/approval_requests/550e8400-e29b-41d4-a716-446655440000" -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Sample response

{
  "approval_request": {
    "status": "pending"
  },
  "success": true
}