Menu

Expand
Rate this page:

Authy API

For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience and new features including:

  • Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, and PHP
  • Access via the Twilio CLI
  • Improved Visibility and Insights
  • Push authentication SDK embeddable in your own application

You are currently viewing the Authy API. The Authy API will continue to be maintained, but any new features and development will be on the Verify API. Check out the FAQ for more information and Verify API Reference to get started.

As part of Twilio's account security offerings, the Twilio Authy API makes it simple to add a second factor of authentication or passwordless logins to your web application. It supports OTP sent via voice and SMS, TOTP generated in the free Authy app (or any compatible authenticator app like Google Authenticator) and push authentication via the free Authy app. To start working with the API, first create an application in the console and get the API Key.

API Base URL

All URLs in the reference documentation use the following base URL:

https://api.authy.com

All requests to the Authy REST API are served over HTTPS. Unencrypted HTTP is not supported.

Authy API Keys

All HTTP requests to the Authy REST API /protected endpoints are protected with an API Secret you pass as an HTTP header X-Authy-API-Key, e.g.:

curl 'https://api.authy.com/protected/json/app/details' \
-H "X-Authy-API-Key: $AUTHY_API_KEY"

The API Key can be found in the Authy section of the Twilio Console after clicking through to your Authy application.

Account security API Key

Supported Formats

The Authy API currently supports JSON and XML formats. When making API calls, you will need to specify json or xml format.

Authy Workflow

This guide shows the 3 steps to completing a basic two-factor verification via SMS. Follow the links for more documentation on advanced features such as sending Push Authentications, registering users without needing their phone number or email, PSD2 compliance, and more.

First, create an Authy Application in the Twilio Console and grab the API Key as demonstrated above.

        
        
        
        
        The AUTHY_ID from this step is necessary to send One-Time Passwords

        Step 1: Create an Authy User

        The AUTHY_ID from this step is necessary to send One-Time Passwords

        An Authy Application is the set of common configurations used to create and check one-time passcodes and manage push authentications. This includes features like:

        • Application Name (used in the one-time password message templates)
        • Token Length
        • ...and more

        One application can be used to send multiple tokens, it is not necessary to create a new application each time.

        Authy Users documentation.

              
              
              
              

              This will send a token to the end user through the specified channel. Supported channels are sms or call.

              If the user has the Authy App, by default, the API will not send the 2FA code via SMS or voice. Instead, a push notification will go to the device, prompting the user to start their app to get the code. You can override this behavior.

              One-time Password documentation.

                    
                    
                    
                    

                    This will check whether the user-provided token is correct. The first time you verify a user you will need to force verification to complete the user registration process.

                    Token Success in response Message in response
                    Correct true Token is valid.
                    Incorrect false Token is invalid

                    One-time Password documentation.

                    Authy Helper Libraries

                    We maintain helper libraries to abstract these API calls for all of our standard web languages.

                    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.

                          
                          
                          

                          Thank you for your feedback!

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

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          Refer us and get $10 in 3 simple steps!

                          Step 1

                          Get link

                          Get a free personal referral link here

                          Step 2

                          Give $10

                          Your user signs up and upgrade using link

                          Step 3

                          Get $10

                          1,250 free SMSes
                          OR 1,000 free voice mins
                          OR 12,000 chats
                          OR more