メニュー

Expand
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ワンタイムパスワード (OTP) - Twilio

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.

ワンタイムパスワードをリクエストする

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

名前 概要
FORMAT
文字列
REST API呼び出しからの返却に想定されるフォーマットです。 json or xml.
AUTHY_ID
integer
The Authy ID of the user to send an SMS TOTP. Create an Authy ID by registering a user. Note that password delivery may be upgraded to use the Authy application; see response parameters below.

パラメーター

名前 概要
force
ブール値(オプション)
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
文字列(オプション)
The optional action or context we are trying to validate. (🏢 not PII )
action_message
文字列(オプション)
Optional message for the specific action. (🏢 not PII )
locale
文字列(オプション)
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 )

レスポンス

名前 概要
success
boolean
Returns true if the request was successful. (🏢 not PII )
message
文字列
A message indicating what happened with the request. (🏢 not PII )
cellphone
文字列
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
文字列
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.

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 user's notification will look like this:

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

        If the user has the Authy app installed the API response will look like this:

        {
            "message":"Ignored: SMS is not needed for smartphones. Pass force=true if you want to actually send it anyway.",
            "cellphone":"+1-XXX-XXX-XX02",
            "device":"android",
            "ignored":true,
            "success":true
        }
        

        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.

              
              
              
              

              カスタムアクション(オプション)

              任意で、特定のトークンを単一のアクションに制限できます。 たとえばワンタイムパスワードを特定のログインリクエストまたはトランザクションに紐づけることができます。 ほとんどの実装では、この機能は必要になることはないでしょう。

              action= および action_message= (オプション)を渡して、特定のアクションに対してのみ有効なコードを送信できます。 これはアプリケーションで異なるアクションの実行に対してコードが必要な場合に便利で、たとえばログイン用のコードの送信時には action=login&action_message="Login code" を渡すことができます。 

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

              • When sending an SMS with custom actions it will always send the SMS even if the user has the Authy app installed. Sending force=true is not necessary.
              • Codes generated through regular sms and the Authy app won't work when sending the custom actions parameters to the verify endpoint.
              • Custom actions is not supported for voice calls.
                    
                    
                    
                    
                    Limit an OTP to a single action

                    音声通話経由でワンタイムパスワードを入力する

                    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

                    名前 概要
                    FORMAT
                    文字列
                    REST API呼び出しからの返却に想定されるフォーマットです。 json or xml.
                    AUTHY_ID
                    integer
                    The Authy ID of the user to send an SMS TOTP. Create an Authy ID by registering a user. Note that password delivery may be upgraded to use the Authy application; see response parameters below.

                    パラメーター

                    名前 概要
                    force
                    ブール値(オプション)
                    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
                    文字列(オプション)
                    The action or context we are trying to validate. (🏢 not PII )
                    action_message
                    文字列(オプション)
                    Message for the specific action. (🏢 not PII )
                    locale
                    文字列(オプション)
                    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 )

                    レスポンス

                    名前 概要
                    success
                    boolean
                    Returns true if the request was successful. (🏢 not PII )
                    message
                    文字列
                    A message indicating what happened with the request. (🏢 not PII )
                    cellphone
                    文字列
                    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
                    文字列
                    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. The API response will look like this:

                          {
                            "message": "Call ignored. User is using  App Tokens and this call is not necessary. Pass force=true if you still want to call users that are using the App.",
                            "cellphone": "+1-XXX-XXX-XX02",
                            "device": "android",
                            "ignored": true,
                            "success": true
                          }
                          

                          Like SMS, 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.

                          ワンタイムパスワードを検証する

                          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

                          名前 概要
                          FORMAT
                          文字列
                          REST API呼び出しからの返却に想定されるフォーマットです。 jsonまたはxmlのいずれかです。
                          TOKEN
                          integer
                          検証中のトークンです。
                          AUTHY_ID
                          文字列
                          The Authy ID of the user validating the TOTP. Create an Authy ID by registering a user.

                          レスポンス

                          名前 概要
                          200 有効なトークンです(下記のメモを参照のこと)*
                          401 無効なトークンです。 かまわずトークンを検証する場合は、force=trueを渡します。 例については下記の「検証を強制する」節を参照してください。

                          * メモ: 新規エンドユーザーに対してはトークンの検証に成功するまで、この呼び出しは200を返します。

                          レスポンス

                          名前 概要
                          token
                          文字列
                          Either "is valid" or "is invalid" (🏢 not PII )
                          success
                          文字列
                          "true" if the code was valid. Please note this field is a String and not a Boolean. (🏢 not PII )
                          device
                          オブジェクト
                          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.

                                
                                
                                
                                

                                The same API is used to verify tokens from TOTP, sms, and voice channels. However when the OTP token is delivered via SMS or voice call, no additional device details are provided and the response will look like:

                                {
                                  "message": "Token is valid.",
                                  "token": "is valid",
                                  "success": "true",
                                  "device": {
                                    "id": null,
                                    "os_type": "sms",
                                    "registration_date": 1490996931,
                                    "registration_method": null,
                                    "registration_country": null,
                                    "registration_region": null,
                                    "registration_city": null,
                                    "country": null,
                                    "region": null,
                                    "city": null,
                                    "ip": null,
                                    "last_account_recovery_at": null,
                                    "last_sync_date": null
                                  }
                                }
                                

                                Force One-Time Password Validation for Unregistered User

                                Use force=true to force verification of a one-time password from a new user.

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

                                force=falseが設定されていない場合のレスポンス

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

                                次の場合のレスポンス: force=true

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

                                Verify Tokens when using Authy 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"
                                }
                                

                                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"
                                }
                                

                                Authenticator App Generated Time-based One-Time Passwords

                                Authy App

                                エンドユーザーがお客様のサービスに新規登録を行う際に使用したものと同じ電話番号でAuthyに登録すると、そのユーザーは自動的にAuthy AppでソフトトークンのTOTPコードを生成できるようになります。 Authy Appの機能を活用するために開発者が追加で行うべきことは何もありません。 Twilio Console内のAuthy設定の「Authy App内でトークンを同期する (Sync tokens in Authy app) 」設定によってこの振る舞いを無効にできます。

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

                                Authenticator SDK

                                Twilio Authenticator SDKを使用すると、Authy Appと同じ機能を任意のモバイルアプリケーションに組み込むことができます。

                                その他の認証App

                                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.

                                QRラベルをカスタマイズして、アカウント名やメールアドレスといったようなトークンについての最終的なユーザーコンテキストを提供するには、QR生成のエンドポイントに対してlabelパラメーターを含めることができます。 このようにすると、多くの認証Appではトークン一覧の中で自動的にラベルを表示します。

                                オンにするには、ブラウザーでTwilio Console内でAuthyアプリケーションにアクセスします。 アプリケーション設定をクリックし、下部までスクロールします。

                                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

                                名前 概要
                                FORMAT
                                文字列
                                REST API呼び出しからの返却に想定されるフォーマットです。 json or xml.
                                AUTHY_ID
                                integer
                                The Authy ID of the user to send an SMS TOTP. Create an Authy ID by registering a user.

                                パラメーター

                                名前 概要
                                qr_size
                                整数(オプション)
                                Dimension of the QR code that will be returned. Square, so only one number required. Default value is 256. Max value is 320. (🏢 not PII )
                                label
                                文字列(オプション)
                                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. Default value is the application name. (📇 PII )
                                      
                                      
                                      
                                      
                                      Rate this page:

                                      ヘルプが必要ですか?

                                      誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。