Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now


Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Authy OneTouch Ruby Quickstart

Getting Started

You can implement OneTouch in two ways:

1) Leverage the OneTouch user experience in the existing Authy mobile application.

You create approval requests via the Authy API. Your users will need to download and install the free Authy app from their mobile vendors store. Authy will send push notifications to your users with the approval request information. Once a user responds an approval request you receive a callback from the Authy API with information of the users response.

The advantages of this approach mean you do not need to implement anything on the mobile side. Just use the existing Authy app and talk to the Authy API using whatever language you prefer.

2) Implement OneTouch inside your mobile app, with Authy SDK.

The SDK allows you total control over the user experience. You can embed this into your existing mobile applications and present the approval/deny action to your user in any way you see fit.

OneTouch with Authy mobile application

Enable OneTouch

Authy customers can enable OneTouch from the Authy dashboard, in the settings section. You will also need to setup a call back url, where OneTouch will send data from user responses to approval requests.

Optionally, if you don't want to receive callbacks from Authy, you can just poll the Authy API to examine the status of any specific notification.

You can use OneTouch as your main two-factor authentication service, or use it in combination with Authy TOTP.

User registration

As soon as you enable OneTouch in an application, any users with the Authy app installed for your service will automatically be enabled for OneTouch. This process generates an RSA public/private key pair to secure the 2FA notifications. Note that the public key will be sent from the mobile app to the Authy server to allow it to complete secured transactions.

The private key will be used by the device to sign the ApprovalRequest responses, and the public key will be used by the OneTouch server and user to verify signatures.

Approval Request with Authy App

Sending Approval Requests

Approval requests are about requesting your users for permission to execute certain actions in your applicaton (e.g. login, money transfer, ssh logins, etc.). Once you create a new ApprovalRequest, the user will receive a push notification in their Authy mobile application. The notification contains details about the activity which help the user decide how to respond. The user then has two buttons, "Approve" and "Deny" and when they select either, the callback is signed and sent to your application with the information.

To create a new approval request, Authy provides the end point:

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

Also, you can use the Authy Ruby gem to create approval requests:

  id: <authy_id>,
  message: 'test message',
  details: { foo: 'bar' },
  hidden_details: { ip: '' }

See Creating Approval Requests for detailed information.

Approval Request with Authy App

Receiving callbacks

You will receive a callback from the Authy API when a user responds to an ApprovalRequest. The callback will be sent to the configured url. Also the HTTP method can be configured. The callback request ContentType is json and contains the following data:

  • device_uuid: The device uuid that responded the approval request
  • callback_action: Will be always approval_request_status
  • uuid: The uuid of the approval request
  • status: The response of the approval request (approve/deny),
  • approval_request: Details of the approval request,
  • signature: The signature created with the device private key
Rate this page:

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.