メニュー

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ユーザー

Before you can secure a user with the Twilio Authy API, you need to create a user. The API requires you set an email, phone number and country code for each user.

When a user is first created, you will receive an authyid which you must then store with the user's profile in your own database. Do not lose this ID - you will use it every time you wish to authenticate a user!

エンドユーザーはAuthyのモバイルまたはデスクトップアプリケーションを使用して、開発者が関知することなく登録されている電話番号を変更できます。 またエンドユーザーは、Authy.com phone change security reviewを使用することもできます。 Webhook API経由で、この電話番号変更時のWebhookを受け取ることができます。

ユーザーを追加する

A user may have multiple email addresses but only one phone is associated with each authy_id. Two separate API calls to register a user with the same device and different emails will return the same authy_id and store both emails for that user.

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

パラメーター

名前 Type 概要
send_install_link_via_sms ブール値(オプション) Value to enable or disable the initial text message. Default=TRUE. Can be set from the Dashboard. (🏢 not PII )
user[email] 文字列(必須) More than one email can be stored per AuthyID, but only the initially created email will display in the Dashboard until it is removed. (📇 PII )
user[cellphone] 文字列(必須) Foreign key for the AuthyID (the AuthyID will be the primary key going forward). You can use dashes, periods, spaces or nothing to separate parts of the cell phone number. (📇 PII )
user[country_code] 文字列(必須) Numeric calling country code of the country Eg: 1 for the US. 91 for India. 54 for Mexico. See: Country code list dropdown (🏢 not PII )

レスポンス

名前 Type 概要
user ユーザー user object contains the AuthyID of the created user. (🏢 not PII )
message 文字列 A message indicating the result of the operation. (🏢 not PII )
success boolean True if the request was successful. (🏢 not PII )
        
        
        
        
              
              
              
              
              Email and phone number must be valid for the request to succeed.

              Create an Authy User (with errors)

              Email and phone number must be valid for the request to succeed.

              Add a user without providing email or phone number

              You might not have the email and the phone number of the user, or if you do, you might not want to share it with Twilio for compliance reasons.

              For those cases you can use our Authy App based onboarding flow. The end user must have the Authy App installed and registered, meaning the end user has already provided their phone number and email to us.

              This feature is only supported in the following versions of the Authy App. End users will have to update their mobile applications to the following versions:

              • iOS 22.4+
              • Android 23.8+
                    
                    
                    
                    

                    First, create a JWT. The token will be used to tie the end user's Authy ID to your application. The token must:

                    1. Follow RFC 7519.
                    2. Be signed with your application's Production API Key found in the Twilio console.
                    3. Contain the following:

                    ペイロード

                    {
                      "iss": "{authy_app_name}",
                      "iat": {issue date in NumericDate},
                      "exp": {expiration date in NumericDate},
                      "context": {
                        "custom_user_id": "{custom_user_id}",
                        "authy_app_id": "{app_authy_id}"
                      }
                    }
                    

                    ヘッダー

                    HS256 is the only algorithm supported.

                    {
                      "alg": "HS256",
                      "typ": "JWT"
                    }
                    

                    iss

                    The issuer param in the JWT payload MUST be the Application name, other value will raise an error in the validation.

                    iat

                    The date the JWT is issued. The difference between iat and exp cannot be more than 15 minutes.

                    exp

                    The expiration time of the JWT. Used to prevent the JWT from being reused in the future. Maximum expiration time allowed is 15 minutes after the current time.

                    custom_user_id

                    Provided by you, uniquely identifies a user. We are not expecting PII or any sensitive data, so please do not provide phone numbers, emails, SSN, or other identifying information. If you only have PII to identify your users we recommend to either:

                    • Create a de-identified ID like a UUID

                    • De-identify the PII by sending us the HMAC of the PII. Use URL safe Base64 encoding.

                    authy_app_id

                    The application id can be retrieved from console by going to Applications selecting the Application, and browsing to settings.

                    During development, you can validate your JWT using https://jwt.io/. The example can be found here.

                    Create a QR Code

                    Next, create a QR string with the following format:

                    authy://account?token={JWT}
                    
                          
                          
                          
                          

                          Generate the QR Code from the transaction string

                          Note: we do not recommend storing the QR code since it can potentially leak sensitive data. Instead, we recommend:

                          1. Sending the QR code as a base64 encoded image in your HTML
                          2. Generating the QR code from your application with a library like github.com/skip2/go-qrcode. For testing, you can use an online generator like http://go-qrcode.appspot.com/.

                          After the QR code is generated display it so your user can scan it with the Authy App.

                          Keep in mind the QR codes expire, so don't display it for more time than the assigned expiration. The mobile device requires internet connectivity to complete the flow.

                          No-PII Registration: Get the User's Authy ID

                          After the end user scans the QR code there are two ways to get the user's Authy ID (required for subsequent verification challenges).

                          1. Poll registration status
                          2. Subscribe to a registration webhook

                          1. Poll registration status

                          GET https://api.authy.com/protected/{FORMAT}/registrations/status?custom_user_id={CUSTOM_USER_ID}
                          

                          URL

                          名前 概要
                          FORMAT
                          文字列
                          The format to expect back from the REST API call. json or xml.
                          CUSTOM_USER_ID
                          文字列
                          ID provided by you to uniquely identify a user. (🏢 not PII )

                          Response Parameters

                          名前 概要
                          status
                          文字列
                          Possible responses:
                          "pending", the user didn't scan the QR code yet.
                          "expired", the received JWT was expired, it was either created with a short duration or the user took to long to scan.
                          "completed", the user was successfully added.
                          authy_id
                          番号
                          Uniquely identifies a user in the Authy API. Use this ID to call other Authy API endpoints.
                                
                                
                                
                                

                                2. Subscribe to a registration webhook

                                You can subscribe to a webhook that will notify you in real time when the registration is successful or not.

                                The payload for event user_registration_completed:

                                  "method": "POST",
                                  "params": {
                                    "events": [
                                      {
                                        "event": "user_registration_completed",
                                        "time": "2019-04-09T22:26:10.503Z",
                                        "objects": {
                                          "app": {
                                            "b_custom_code_allowed": false,
                                            "b_custom_message_allowed": false,
                                            "s_account_sid": "AC5f123456eabfa99ee3441ef1e84ad528",
                                            "s_device_app": null,
                                            "s_errors": "",
                                            "s_id": "54321",
                                            "s_name": "Application Name",
                                            "s_type": null
                                          },
                                          "registration": {
                                            "s_app_id": 54321,
                                            "s_authy_id": 123456,
                                            "s_custom_id": "885de433faedf8475426f11baeee2424f88fd935"
                                          },
                                          "user": {
                                            "as_authy_ids": [
                                              "123456"
                                            ],
                                            "b_banned": false,
                                            "s_authy_id": "123456",
                                            "s_country_code": "57",
                                            "s_errors": "",
                                            "s_locale": "en",
                                            "s_phone_number": "953a0fd8c9ec2a9f16a5ce58183cfa03"
                                          }
                                        },
                                        "request": {
                                          "id": "413fd53c-09af-43d6-8390-c346de8ccf0c",
                                          "ip": "IPv4_99a65f1a9e58fe49150aed5a188459b9b0b47157"
                                        },
                                        "public": true
                                      }
                                    ],
                                    "webhook_id": "WH_50087ea9-9568-4839-9191-b43908a4abd4"
                                  },
                                  "url": "https://example.io/webhook"
                                }
                                

                                The payload for event user_registration_failed:

                                {
                                  "method": "POST",
                                  "params": {
                                    "events": [
                                      {
                                        "event": "user_registration_failed",
                                        "time": "2019-04-09T22:26:10.503Z",
                                        "objects": {
                                          "app": {
                                            "b_custom_code_allowed": false,
                                            "b_custom_message_allowed": false,
                                            "s_account_sid": "AC5f586933eabfa99ee3441ef1e84ad528",
                                            "s_device_app": null,
                                            "s_errors": "",
                                            "s_id": "54321",
                                            "s_name": "Application Name",
                                            "s_type": null
                                          },
                                          "error": {
                                            "s_code": "60000"
                                          }
                                        },
                                        "request": {
                                          "id": "413fd53c-09af-43d6-8390-c346de8ccf0c",
                                          "ip": "IPv4_99a65f1a9e58fe49150aed5a188459b9b0b47157"
                                        },
                                        "public": true
                                      }
                                    ],
                                    "webhook_id": "WH_50087ea9-9568-4839-9191-b43908a4abd4"
                                  },
                                  "url": "https://example.io/webhook"
                                }
                                

                                ユーザーステータスをリクエストする

                                ユーザーが作成されて開発されたアプリケーションに登録されルト、Twilioからそのユーザーについての情報をリクエストできます。 Userステータスコールを使用すると、下記が受信されます:

                                1. country_code
                                2. phone number(電話番号): 電話番号の下4桁です。
                                3. devices: デバイスの一覧です。 取りうる値: android、android_tablet、ios、iphone、iphone_sdk、chrome、authy_chrome、sms、android_sdk
                                4. registered(登録状態): AuthyのモバイルまたはデスクトップAppが登録されているとtrueを返します。
                                5. confirmed(確認済): ユーザーが以前に有効なコードを使用したことがある場合はtrueを返します。
                                GET https://api.authy.com/protected/{FORMAT}/users/{USER ID}/status
                                

                                パラメーター

                                名前 Type 概要
                                user_ip 文字列 IP of the user requesting to see the application details. Optional. (📇 PII )

                                レスポンス

                                名前 Type 概要
                                status ディクショナリー Status contains information about the user. (🏢 not PII )
                                message 文字列 A message indicating the result of the operation. (🏢 not PII )
                                success boolean True if the request was successful. (🏢 not PII )
                                      
                                      
                                      
                                      

                                      ユーザーを削除する

                                      開発者のアプリケーションからエンドユーザーを削除したい場合は、削除APIを使用してこれを行えます。 メモ: ユーザーの削除はトークンの検証を直ちに無効にします。

                                      Best practice is to remove a user if they disable Two-factor Authentication or remove an account with your App. If you accidentally remove a user, you can recover users through the Console - but we suggest that you instead go through your registration flow again.

                                      curl -X POST https://api.authy.com/protected/{FORMAT}/users/{USER ID}/remove -H "X-Authy-API-Key: {KEY}"
                                      

                                      パラメーター

                                      名前 Type 概要
                                      user_ip 文字列(オプション) The ip requesting to remove the user (📇 PII )

                                      レスポンス

                                      名前 Type 概要
                                      success boolean True if the user was scheduled for deletion. (🏢 not PII )
                                      message 文字列 処理結果を示すメッセージです。
                                      (🏢 not PII )
                                            
                                            
                                            
                                            
                                            Rate this page:

                                            ヘルプが必要ですか?

                                            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.