Authy Push Authentications

Push authentication (using push notifications) has the best user experience for second-factor and passwordless authentication and additionally offers the highest level of security. For users with the ability to install an app on their mobile device or computer, these ApprovalRequests can be sent and verified through our REST API.

For information on other channels such as SMS or soft tokens, see the Authy API One-time Passwords documentation.

Create an Approval Request

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 Mobile app(s), Desktop app(s), and any SDK-driven apps. Only the subject of the transaction is sent through Google or Apple push channels. If push notifications fail or delay, the user can still retrieve pending transactions by opening the Authy app or an SDK app manually.

POST https://api.authy.com/onetouch/{FORMAT}/users/2/approval_requests?api_key={KEY}

Parameters

Name Type Description
message String Required This is the subject shown to the user when the push notification arrives.
details Hash Dictionary containing any ApprovalRequest details you'd like to present to the user to assist their decision to approve or deny a transaction. We will also automatically add a timestamp to transactions. See example below for an example on how to use details.
hidden_details Hash Dictionary containing the approval request details hidden to user. This information will be preserved in transaction records but not presented to the user, so it may be useful for your business logic and routing.
logos Hash A dictionary containing override logos that will be shown to user in the push authentication transaction details. By default, we send the logos uploaded through the console.
seconds_to_expire Integer The number of seconds a transaction is valid without user response (pending) before expiring. Defaults to 86400 (one day); 0 will never expire. This should not be set too low as users need time to evaluate a request.

Response

Name Type Description
approval_request Hash Hash containing the keys & values for the ApprovalRequest.
uuid String Unique transaction ID of the ApprovalRequest. You'll need the uuid to query the request status or tie future callbacks to this ApprovalRequest.
created_at Datetime The date and time that we created the ApprovalRequest.
status String Tracks the current state of the ApprovalRequest between pending a user response, approved, denied, or expired.

Example

Creating a new approval request

curl "https://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[transaction_num]="TR139872562346" \
-d seconds_to_expire=120
Sample Response
{  
   "approval_request":{  
      "uuid":"fd285c30-97f8-0135-cfa7-1241e5695bb0"
   },
   "success":true
}

Use a Custom Logo in an Approval Request

By default, all the ApprovalRequests created will be shown to the user using the logo defined in your Account Security application in the Two-factor Authentication dashboard. However, you can provide a custom image at the time of the request.

Note: All image URLs must be served over HTTPS and not HTTP. Due to mobile platform restrictions, image requests must be over a secure channel.

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 "https://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]="99998888" \
-d hidden_details[ip_address]='10.10.10.10' \
-d seconds_to_expire=120
-d logos[][res]='default' \
-d logos[][url]='https://example.com/logos/default.png' \
-d logos[][res]='low' \
-d logos[][url]='https://example.com/logos/low.png'

Sample response

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


Check Approval Request Status

There are two ways for you to check on ApprovalRequest status. You can poll the endpoint below for the status of an ApprovalRequest or you can use a webhook callback. Polling is the quickest way to get started using and testing the endpoint.

In your final application, we recommend exposing a URL to Twilio and using webhooks. With a webhook, we will call your URL immediately when a user reacts to an ApprovalRequest. Webhooks are a more scalable solution than polling. For redundancy you can implement both webhook callbacks and long-polling.

See here for how to validate incoming Twilio Authy API requests, or read more on Webhooks.

In order to implement polling, you can hit the following endpoint repeatedly until the status changes. We suggest polling once per second for the best user experience.

GET https://api.authy.com/onetouch/{FORMAT}/approval_requests/:uuid?api_key={KEY}

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 and other attributes as you can see in the example below. If you are using older client api version may the response will differ from the actual sample and only will contain the files describe below.

Only old version of OneTouch

[authy_id, callback_action, uuid, app_name, app_id, created_at, updated_at, seconds_to_expire, status, created_at_time]

You will get different status responses depending on whether the response is in pending state or approved or denied state.

Example
curl -i "https://api.authy.com/onetouch/json/approval_requests/c31f7620-9726-0135-6e6f-0ad8af7cead6" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
Pending State
{  
   "approval_request":{  
      "_app_name":"OwlBank",
      "_app_serial_id":15861,
      "_authy_id":245624,
      "_id":"59e8eaaa1e145e587b923fc1",
      "_user_email":"help@twilio.com",
      "app_id":"542b1b82f92ea10597000d6d",
      "created_at":"2017-10-19T18:10:50Z",
      "notified":false,
      "processed_at":"2017-10-19T18:11:37Z",
      "seconds_to_expire":86400,
      "status":"pending",
      "updated_at":"2017-10-19T18:11:37Z",
      "user_id":"145642564",
      "uuid":"c31f7620-9726-0135-6e6f-0ad8af7cead6"
   },
   "success":true
}
Approved or Denied State

(Note that 'status' would be denied for user denial.)

{  
   "approval_request":{  
      "_app_name":"OwlBank",
      "_app_serial_id":15861,
      "_authy_id":245624,
      "_id":"59e8eaaa1e145e587b923fc1",
      "_user_email":"help@twilio.com",
      "app_id":"542b1b82f92ea10597000d6d",
      "created_at":"2017-10-19T18:10:50Z",
      "notified":false,
      "processed_at":"2017-10-19T18:11:37Z",
      "seconds_to_expire":86400,
      "status":"approved",
      "updated_at":"2017-10-19T18:11:37Z",
      "user_id":"145642564",
      "uuid":"c31f7620-9726-0135-6e6f-0ad8af7cead6",
      "device":{  
         "city":"San Francisco",
         "country":"United States",
         "ip":"192.168.92.226",
         "region":"California",
         "registration_city":"New York",
         "registration_country":"United States",
         "registration_ip":"127.0.0.4",
         "registration_method":"push",
         "registration_region":"New York",
         "os_type":"ios",
         "last_account_recovery_at":null,
         "id":2456245,
         "registration_date":1506380735,
         "last_sync_date":1508436616
      }
   },
   "success":true
}

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.