Menu

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 One-Time Passwords (OTP)

Before sending a One-Time Password:

  1. Create an Authy Application (see Applications documentation)
  2. Create a User (see Users documentation)

Once a user has been registered with your Twilio Authy application and receives an AuthyID, you can now implement 2FA, passwordless login or protect an in-application high-value transaction. Using the Authy API, you can send one-time passwords over voice or SMS channels.

Users can also install the free Authy app or use our SDK to generate offline TOTP codes (soft tokens). Soft tokens do not require wireless connectivity to issue and verify.

The Authy API is used to verify a user has access to the right phone number (for SMS and Voice channels) or has access to the right trusted device (for TOTP via the Authy App or use of the SDK).

Twilio's Authy API follows the algorithms described in RFC 6238 and RFC 4226 to generate TOTP (Time-Based One-Time Passwords) passwords. It is also possible to use your own hardware tokens, please contact us for information on how to enable this type of 2FA.

Request a One-Time Password

When you call the API to start either an SMS or voice-based authentication, it automatically checks to see if that user has previously downloaded the Authy app or has an app installed that uses our SDK. 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.

If a user has no record of installing a device, then the API will continue to send the code via SMS or voice. You can override the default behavior to force the sending of code via SMS or voice every time. This is a useful override if a user is specifically selecting "Send SMS" or "Get code via voice call" in your application UI.

For information on timing and other constraints like rate limiting, see our two-factor authentication best practices.

GET https://api.authy.com/protected/{FORMAT}/sms/{AUTHY_ID}

URL

Name Description
FORMAT
String
The format to expect back from the REST API call. json or xml.
AUTHY_ID
Integer
The Authy ID of the user to send an SMS TOTP. Note that password delivery may be upgraded; see below table.

Parameters

Name Description
force
Boolean (optional)
Default is false. Set to true to send one-time passwords over the SMS channel even if the user has an Authy or SDK enabled app installed. Configure default behavior in the console. (🏢 not PII )
action
String (optional)
The optional action or context we are trying to validate. (🏢 not PII )
action_message
String (optional)
Optional message for the specific action. (🏢 not PII )
locale
String (optional)
The language of the message received by user. If no locale is given, Twilio will try to autodetect it based on the country code. English is used if no locale is autodetected. More details below (🏢 not PII )

Response

Name Description
success
Boolean
Returns true if the request was successful. (🏢 not PII )
message
String
A message indicating what happened with the request. (🏢 not PII )
cellphone
String
The country code and last two digits of phone number used to send the message with the rest obfuscated. (🏢 not PII )
ignored
Boolean
True if we detected an Authy or SDK enabled app installed and we upgraded the OTP delivery channel from 'SMS' to Push Notification. Authy or SDK users are redirected directly to the requested token. (🏢 not PII )
device
String
The type of the last device used by the user. This is only returned when we upgraded delivery from SMS. (🏢 not PII )

Supported Languages

Supported languages are: Afrikaans (af), Arabic (ar), Catalan (ca), Chinese (zh), Chinese (Mandarin) (zh-CN), Chinese (Cantonese) (zh-HK), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Finnish (fi), French (fr), German (de), Greek (el), Hebrew (he), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Malay (ms), Norwegian (nb), Polish (pl), Portuguese - Brazil (pt-BR), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Tagalog (tl), Thai (th), Turkish (tr), Vietnamese (vi). We support the format country-region as described in IETF's BPC 47. If no region is given (or supported), there will be a default by country.

Send a One-time Password Via SMS

        
        
        
        

        Default Behavior for Users with the Authy App Installed

        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. The notification will look like this:

        Authy push notification - app installed on attempt to send an SMS

              
              
              
              

              Override Default Behavior and Force Sending SMS

              You can override this behavior and force sending an SMS or Voice call. This is a useful override if a user is specifically selecting "Send SMS" or "Get code via voice call" in your application UI.

                    
                    
                    
                    

                    Custom Actions (Optional)

                    Optionally, you can limit a specific token to a single action, for example coupling a one-time password to a specific logon request or transaction. Most implementations will not need this feature.

                    You can pass action= and action_message= (optional) to send a code that is only valid for the given action. This is useful if you require codes to perform different actions on your app, for example, you can pass action=login&action_message="Login code" when sending a login code.

                    When using this option you must pass the same action when verifying the code.

                          
                          
                          
                          
                          Limit an OTP to a single action

                          Send a One-Time Password via Voice

                          For users that don't own a smartphone or are having trouble with SMS Tokens, Authy allows you to use phone calls instead. Like SMS, by default this call will be ignored if the user is using the Authy Mobile app. You can override the default behavior with the force parameter.

                          GET https://api.authy.com/protected/{FORMAT}/call/{AUTHY_ID}
                          

                          URL

                          Name Description
                          FORMAT
                          String
                          The format to expect back from the REST API call. json or xml.
                          AUTHY_ID
                          Integer
                          The Authy ID of the user to send an SMS TOTP. Note that password delivery may be upgraded; see below table.

                          Parameters

                          Name Description
                          force
                          Boolean (optional)
                          Default is false. Set to true to send one-time passwords over the Voice channel even if the user has an Authy or SDK enabled app installed. Configure default behavior in the console. (🏢 not PII )
                          action
                          String (optional)
                          The action or context we are trying to validate. (🏢 not PII )
                          action_message
                          String (optional)
                          Message for the specific action. (🏢 not PII )
                          locale
                          String (optional)
                          The language of the message received by user. If no locale is given, Twilio will try to autodetect it based on the country code. English is used if no locale is autodetected. More details above. (🏢 not PII )

                          Response

                          Name Description
                          success
                          Boolean
                          Returns true if the request was successful. (🏢 not PII )
                          message
                          String
                          A message indicating what happened with the request. (🏢 not PII )
                          cellphone
                          String
                          The country code and last two digits of phone number used to send the message, with the rest obfuscated. (🏢 not PII )
                          ignored
                          Boolean
                          True if we detected an Authy or an SDK enabled app installed and we upgraded the OTP delivery channel from 'Voice' to Push Notification. Authy or SDK users are redirected directly to the requested token. (🏢 not PII )
                          device
                          String
                          The type of the last device used by the user. This is only returned when we upgraded delivery from a voice call. (🏢 not PII )
                                
                                
                                
                                

                                Default Behavior for Users with the Authy App Installed

                                If the user has the Authy App, by default, the API will not call the user. See above for more details.

                                      
                                      
                                      
                                      

                                      You can pass force=true as a parameter to this API. This will force the phone call to start even if the user is using the Authy app.

                                      Verify a One-Time Password

                                      To verify a one-time password pass in the user provided token and the user authy_id. Twilio will use HTTP status codes for the response.

                                      GET https://api.authy.com/protected/{FORMAT}/verify/{TOKEN}/{AUTHY_ID}
                                      

                                      URL

                                      Name Description
                                      FORMAT
                                      String
                                      The format to expect back from the REST API call. json, or xml.
                                      TOKEN
                                      Integer
                                      The token you are verifying.
                                      AUTHY_ID
                                      String
                                      The Authy ID of the user validating the TOTP.

                                      Responses

                                      Name Description
                                      200 Valid token (see note below)*
                                      401 Invalid token. If you wish to verify the token anyway, pass force=true. See the force verification section below for an example.

                                      *Note: Until you successfully verify a token for a new user, this call will return 200.

                                      Response

                                      Name Description
                                      token
                                      String
                                      Either "is valid" or "is invalid" (🏢 not PII )
                                      success
                                      String
                                      "true" if the code was valid. Please note this field is a String and not a Boolean. (🏢 not PII )
                                      device
                                      Object
                                      An object including some details about the device used to get or generate the token. The fields included in the device object are: city, region, country, ip, registration_city, registration_region, registration_country, registration_ip, registration_date, os_type, last_account_recovery_at and id. (📇 PII )

                                      When the TOTP token is generated in the Authy app or in the SDK, additional device information and registration data are provided in the response.

                                            
                                            
                                            
                                            

                                            Verify a Token received via SMS or Voice

                                            When the OTP token is delivered via SMS or Voice call, no additional device details are provided.

                                                  
                                                  
                                                  
                                                  

                                                  Invalid Tokens

                                                  A verification attempt with an invalid token will return a 401 Unauthorized with the following Response body:

                                                  {
                                                    "message": "Token is invalid",
                                                    "token": "is invalid",
                                                    "success": false,
                                                    "errors": {
                                                      "message": "Token is invalid"
                                                    },
                                                    "error_code": "60020"
                                                  }
                                                  

                                                  Example: Force One-Time Password Validation for Unregistered User

                                                  Use force=true to force verification of a one-time password from a new user. Otherwise, until one token has been successfully verified for that user we will always return 200.

                                                  curl -i "http://api.authy.com/protected/json/verify/{TOKEN}/{AUTHY_ID}" \
                                                    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
                                                  

                                                  Response if force=false or Not Set

                                                  {
                                                    "token":"Not checked. User has not yet finished the registration process. Pass force=true to this API to check regardless (more secure)."
                                                  }
                                                  

                                                  Response if force=true

                                                  {
                                                    "errors": {
                                                      "token":"is invalid"
                                                    }
                                                  }
                                                  

                                                  Custom Actions

                                                  When using custom actions to send SMS you have to pass action= to validate the one-time password.
                                                  For more information see Custom Actions.

                                                  {
                                                    "token": "is valid"
                                                  }
                                                  

                                                  Authenticator App Generated Time-based One-Time Passwords

                                                  Authy App

                                                  When you enroll a user, they will automatically be able to generate Soft Token TOTP codes in the Authy App if they register for Authy with the same phone number that you used to enroll them. You do not need to do anything additional to take advantage of the Authy app. You can disable this behavior with the 'Sync tokens in Authy app' setting in the Authy settings in the Twilio Console.

                                                  To validate these One-Time Passwords, see Verify a One-Time Password below.

                                                  Authenticator SDK

                                                  You can embed the same functionality from the Authy app into any mobile application using the Twilio Authenticator SDK.

                                                  Other Authenticator Apps

                                                  In order to support other Authenticator apps, like Google Authenticator, you will need to display a QR code to your users that contain a compatible OTP secret. The API will return a link to a valid QR code.

                                                  In order to customize the QR label and give the final user context about the token like account name or email, you can include the label param in the QR generation endpoint. That way many Authenticator apps will automatically render the label in the token list.

                                                  To enable, browse to your Authy application in the Twilio Console. Click on your App's Settings and scroll to the bottom.

                                                  Note, each QR code request will generate a unique TOTP seed. As such, you can only have a single active QR code per user per protected site. Requesting an additional QR code for a user will invalidate the previous secret and generate a new QR code.

                                                  When providing a QR code to a user, be sure to have them validate the code before applying 2FA protection to their account.

                                                  POST https://api.authy.com/protected/{FORMAT}/users/{AUTHY_ID}/secret
                                                  

                                                  URL

                                                  Name Description
                                                  FORMAT
                                                  String
                                                  The format to expect back from the REST API call. json or xml.
                                                  AUTHY_ID
                                                  Integer
                                                  The Authy ID of the user to send an SMS TOTP. Note that password delivery may be upgraded; see below table.

                                                  Parameters

                                                  Name Description
                                                  qr_size
                                                  Integer (optional)
                                                  Dimension of the QR code that will be returned. Square, so only one number required. (🏢 not PII )
                                                  label
                                                  String (optional)
                                                  A custom label for the QR code, this field will be shown by the Authenticator app, it gives context to the user, like the account email. (📇 PII )

                                                  This example adds a GenericToken to a User and returns the QR code with the secret to be scanned by the user in the Authenticator App. The QR size will be 300x300 pixels.

                                                        
                                                        
                                                        
                                                        
                                                        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.