メニュー

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プッシュ認証

Push authentication (using push notifications) has the best user experience for second-factor and passwordless authentication and additionally offers the highest level of security. All requests are fully encrypted, end to end and allow for non-repudiated transactions.

For users with the ability to install an app on their mobile device or computer, these ApprovalRequests can be sent and verified through our REST API. For information on other channels such as SMS or soft tokens, see the Authy API One-time Passwords documentation.

承認リクエストを作成する

これによって指定されたAuthy IDに対して新規の承認リクエストを作成し、AuthyモバイルApp、デスクトップApp、およびSDKの組み込まれたAppへのプッシュ通知とともにエンドユーザーに対して送信されます。 GoogleまたはAppleのプッシュチャネルを通じては、トランザクションの件名のみが送信されます。 プッシュ通知が失敗または遅延した場合でも、ユーザーはAuthy AppまたはSDKの組み込まれたAppを手動で開くことで保留されたトランザクションを取得できます。

POST https://api.authy.com/onetouch/{FORMAT}/users/{AUTHY_ID}/approval_requests

URL

名前 Type 概要
FORMAT 文字列 REST API呼び出しからの返却に想定されるフォーマットです。 jsonまたはxmlのいずれかです。
AUTHY_ID integer The Authy ID of the user to send a Push Authentication.

パラメーター

名前 Type 概要
message 文字列 Required This is the subject shown to the user when the push notification arrives. (📇 PII )
details ハッシュ Dictionary containing any ApprovalRequest details you'd like to present to the user to assist their decision to approve or deny a transaction. We will also automatically add a timestamp to transactions. See example below for an example on how to use details. (📇 PII )
hidden_details ハッシュ Dictionary containing the approval request details hidden to user. This information will be preserved in transaction records but not presented to the user, so it may be useful for your business logic and routing. (📇 PII )
logos ハッシュ A dictionary containing override logos that will be shown to user in the push authentication transaction details. By default, we send the logos uploaded through the console. (🏢 not PII )
seconds_to_expire integer The number of seconds a transaction is valid without user response (pending) before expiring. Defaults to 86400 (one day); 0 will never expire. This should not be set too low as users need time to evaluate a request. (🏢 not PII )

レスポンス

名前 Type 概要
approval_request ハッシュ Hash containing the keys & values for the ApprovalRequest. (📇 PII )
uuid 文字列 Unique transaction ID of the ApprovalRequest. You'll need the uuid to query the request status or tie future callbacks to this ApprovalRequest. (🏢 not PII )
created_at Datetime The date and time that we created the ApprovalRequest. (🏢 not PII )
status 文字列 Tracks the current state of the ApprovalRequest between pending a user response, approved, denied, or expired. (🏢 not PII )

新規承認リクエストの作成

curl "https://api.authy.com/onetouch/json/users/2/approval_requests" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
-d message="Login requested for a CapTrade Bank account." \
-d details[username]="Bill Smith" \
-d details[location]="California, USA" \
-d details[Account Number]="981266321" \
-d hidden_details[transaction_num]="TR139872562346" \
-d seconds_to_expire=120
レスポンス例
{  
   "approval_request":{  
      "uuid":"fd285c30-97f8-0135-cfa7-1241e5695bb0"
   },
   "success":true
}

承認リクエストにカスタムロゴを使用する

既定では、作成されたすべてのApprovalRequestでは二要素認証ダッシュボード内のAccount Securityアプリケーションで定義されたロゴがエンドユーザーに対して表示されます。 しかし、リクエスト時にカスタム画像を提供することも可能です。

メモ: すべての画像URLはHTTPではなくHTTPSでアクセスできなければなりません。 モバイルプラットフォームにおける制限により、画像へのリクエストはセキュアなチャンネルを使用しなければなりません。

logos パラメーターは配列またはオブジェクトである必要があり、各オブジェクトには2つのフィールド: res (解像度)、そしてurl(ロゴのホストされている場所)があります。 logosパラメーターが含まれる場合、default値を伴うresフィールドが含まれる必要があります。 これが含まれない場合、エラーが返されます。

ロゴで利用可能なresフィールドのその他のオプションは以下の通りです:

  • default (各解像度に対するロゴを指定しない場合、この値が使用されます)
  • low (低解像度のデバイスに使用されます)
  • med (中解像度のデバイスで使用されます)
  • high (高解像度のデバイスで使用されます)

カスタム・ロゴ付きの承認リクエストの新規作成

curl "https://api.authy.com/onetouch/json/users/2/approval_requests" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
-d message="Login requested for a CapTrade Bank account." \
-d details[username]="Bill Smith" \
-d details[location]="California, USA" \
-d details[Account Number]="99998888" \
-d hidden_details[ip_address]='10.10.10.10' \
-d seconds_to_expire=120
-d logos[][res]='default' \
-d logos[][url]='https://example.com/logos/default.png' \
-d logos[][res]='low' \
-d logos[][url]='https://example.com/logos/low.png'

レスポンス例

{
  "approval_request": {
    ...
    "uuid":"550e8400-e29b-41d4-a716-446655440000"
    ...
  },
  "success":true
}


承認リクエストのステータスを確認する

ApprovalRequestステータスの確認には2つの方法があります。 下記のエンドポイントをポーリングしてApprovalRequestのステータスを確認するか、Webhookコールバックを使用できます。 ポーリングは、使用やテストを始めるのにもっとも手っ取り早い方法です。

本番環境のアプリケーションでは、URLをTwilioからアクセスできるようにし、Webhookを使用することを推奨します。 Webhookを使用すると、エンドユーザーがApprovalRequestに応答後、直ちに開発者のサーバーのURLにリクエストを送信します。 Webhookはポーリングよりもスケーラブルなソリューションになります。 冗長性を確保するため、Webhookコールバックとロングポーリングの両方を実装することができます。

こちらの受信Twilio Authy APIリクエストの検証方法をご覧いただくか、Webhookについての詳細をお読みください。

ポーリングの実装を行うには、ステータスが変化するまで下記のエンドポイントを繰り返し叩きます。 最良のユーザー体験のため、ポーリングは毎秒行うことを推奨します。

GET https://api.authy.com/onetouch/{FORMAT}/approval_requests/:uuid

パラメーター

名前 Type 概要
uuid 文字列 Required. The approval request ID. (Obtained from the response to an ApprovalRequest) (🏢 not PII )

レスポンス

名前 Type 概要
approval_request ハッシュ Hash containing the status of the approval request and other attributes as you can see in the example below. If you are using older client api version may the response will differ from the actual sample and only will contain the files describe below. (📇 PII )

旧バージョンのOneTouchのみ

[authy_id, callback_action, uuid, app_name, app_id, created_at, updated_at, seconds_to_expire, status, created_at_time]

レスポンスがpending(保留)状態、approved(承認)あるいはdenied(否認)状態かに応じて異なるstatusのレスポンスが得られます。

curl -i "https://api.authy.com/onetouch/json/approval_requests/c31f7620-9726-0135-6e6f-0ad8af7cead6" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
状態のポーリング
{  
   "approval_request":{  
      "_app_name":"OwlBank",
      "_app_serial_id":15861,
      "_authy_id":245624,
      "_id":"59e8eaaa1e145e587b923fc1",
      "_user_email":"help@twilio.com",
      "app_id":"542b1b82f92ea10597000d6d",
      "created_at":"2017-10-19T18:10:50Z",
      "notified":false,
      "processed_at":"2017-10-19T18:11:37Z",
      "seconds_to_expire":86400,
      "status":"pending",
      "updated_at":"2017-10-19T18:11:37Z",
      "user_id":"145642564",
      "uuid":"c31f7620-9726-0135-6e6f-0ad8af7cead6"
   },
   "success":true
}
状態を承認または否認する

(ユーザーの否認に対しては「status」がdeniedとなることに注意してください)

{  
   "approval_request":{  
      "_app_name":"OwlBank",
      "_app_serial_id":15861,
      "_authy_id":245624,
      "_id":"59e8eaaa1e145e587b923fc1",
      "_user_email":"help@twilio.com",
      "app_id":"542b1b82f92ea10597000d6d",
      "created_at":"2017-10-19T18:10:50Z",
      "notified":false,
      "processed_at":"2017-10-19T18:11:37Z",
      "seconds_to_expire":86400,
      "status":"approved",
      "updated_at":"2017-10-19T18:11:37Z",
      "user_id":"145642564",
      "uuid":"c31f7620-9726-0135-6e6f-0ad8af7cead6",
      "device":{  
         "city":"San Francisco",
         "country":"United States",
         "ip":"192.168.92.226",
         "region":"California",
         "registration_city":"New York",
         "registration_country":"United States",
         "registration_ip":"127.0.0.4",
         "registration_method":"push",
         "registration_region":"New York",
         "os_type":"ios",
         "last_account_recovery_at":null,
         "id":2456245,
         "registration_date":1506380735,
         "last_sync_date":1508436616
      }
   },
   "success":true
}
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.