メニュー

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

Once a user (see Users documentation) 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, and users can additionally use authentication application or SDK linked soft tokens.

SMSまたは音声通話を受け取れないエンドユーザーについては、原因としてワイヤレス接続が利用できないことが考えられます。 そのような場合は無料のAuthy AppをインストールするかTwilioのSDKを使用して、オフラインTOTPトークン(Soft Token)を生成できます。 またAPIを使用してこれらのトークンを確認したり、ユーザーが本当に電話番号へのアクセス(SMSおよび音声通話の場合)、あるいは信頼済みデバイス(Authy AppまたはSDKを使用する場合)を保持しているか検証を行います。

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

認証Appで生成されたワンタイムパスワード

Authy App

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

これらのワンタイムパスワードを検証するには、下記の「ワンタイムパスワードを検証する」節を参照してください。

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

名前 Type 概要
FORMAT 文字列 REST API呼び出しからの返却に想定されるフォーマットです。 jsonまたは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.

パラメーター

名前 Type 概要
qr_size 整数(オプション) Dimension of the QR code that will be returned. Square, so only one number required. (🏢 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. (📇 PII )

下記の例ではGenericTokenをエンドユーザーに追加して、認証App内でそのユーザーによってスキャンされるシークレットを含んだQRコードを返します。 QRコードのサイズは300x300ピクセルになります。

curl -XPOST "https://api.authy.com/protected/json/users/2/secret" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
-d label="AppName(myuser@example.com)" \
-d qr_size="300"

サンプルレスポンス:

{
  “label": ”AppName(myuser@example.com)”,
  “Issuer”: “AppName”,
  “qr_code”: “https://[qr_code]”
  "success":true
}

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

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 there is a record of a device, 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. Note this behavior can be over-ridden 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.

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

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

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

このオプションを使用する場合、コードの検証時と同じactionを渡さなければなりません

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

URL

名前 Type 概要
FORMAT 文字列 REST API呼び出しからの返却に想定されるフォーマットです。 jsonまたはxmlのいずれかです。
AUTHY_ID integer SMSのTOTPを送信するユーザーのAuthy IDです。 パスワード配信はアップグレードされる可能性があります。 下記の表を参照してください。

パラメーター

名前 Type 概要
force ブール値(オプション) We suggest using the default, false, as OTP verifications are forward compatible, perhaps setting true for user retries. When true, we will send one-time passwords over the SMS channel even if the user has an Authy or SDK enabled app installed. You can also configure the default behavior through 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. In case that no locale is autodetected, English will be used. 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. (🏢 not PII )

レスポンス

名前 Type 概要
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 )


SMS経由でワンタイムパスワードを送信する

curl -i "http://api.authy.com/protected/json/sms/234572" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
ユーザーがAuthyクライアントまたはSDKを使用しない場合のサンプルレスポンス
{
    "success":true,
    "message":"SMS token was sent",
    "cellphone":"+1-XXX-XXX-XX02"
}
エンドユーザーがAuthy ClientまたはSDKを所持している場合のサンプルレスポンス
{
    "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
}

このAPIに force=true パラメーターを渡すことができます。 これはユーザーがAuthy ClientまたはSDKを使用していてもなお、SMSを送信するよう指定するものです。

curl "http://api.authy.com/protected/json/sms/567345?force=true" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
レスポンス例
{
    "success":true,
    "message":"SMS token was sent",
    "cellphone":"+1-XXX-XXX-XX02"
}

カスタム・アクションの例

curl "http://api.authy.com/protected/json/sms/126435?action=change_preferences" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
レスポンス例
{
    "success":true,
    "message":"SMS token was sent"
}


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

スマートフォンを持っていなかったり、SMSトークンがうまく機能しないエンドユーザー向けに、Authyでは代わりに音声通話を使用することができます。 ユーザーがAuthyモバイルAppを使用している場合、この通話は無視されます。

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

URL

名前 Type 概要
FORMAT 文字列 REST API呼び出しからの返却に想定されるフォーマットです。 jsonまたはxmlのいずれかです。
AUTHY_ID integer 音声通話のTOTPを送信するユーザーのAuthy IDです。 パスワード配信はアップグレードされる可能性があります。 下記の表を参照してください。

パラメーター

名前 Type 概要
force ブール値(オプション) We suggest using the default, false, as OTP verifications are forward compatible, perhaps setting true for user retries. When true, we will send one-time passwords over the Voice channel even if the user has an Authy or an SDK enabled app installed installed. You can also configure the default behavior through 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 voice call message received by user. If no locale is given, Twilio will try to autodetect it based on the country code. In case that no locale is autodetected, English will be used. Supported languages are: Afrikaans (af), Arabic (ar), Catalan (ca), 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. (🏢 not PII )

レスポンス

名前 Type 概要
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 )

音声通話によるワンタイムパスワードのリクエスト

curl -i "http://api.authy.com/protected/json/call/209412" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
ユーザーがAuthy AppまたはSDKの組み込まれたAppを持っていない場合のサンプルレスポンス
{
    "success":true,
    "message":"Call started...",
    "cellphone":"+1-XXX-XXX-XX02"
}
ユーザーがAuthy AppまたはSDKの組み込まれたAppを使用した場合のサンプルレスポンス
{
    "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
}

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.

curl -i "http://api.authy.com/protected/json/call/142352?force=true"  \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
レスポンス例
{
    "success":true,
    "message":"Call started...",
    "cellphone":"+1-XXX-XXX-XX02"
}


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

To verify a one-time password simply pass in the user provided the 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

名前 Type 概要
FORMAT 文字列 REST API呼び出しからの返却に想定されるフォーマットです。 jsonまたはxmlのいずれかです。
token integer 検証中のトークンです。
AUTHY_ID 文字列 TOTPを検証しているユーザーのAuthy IDです。

レスポンス

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

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

レスポンス

名前 Type 概要
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, as well as registration data, are provided.

curl -i "http://api.authy.com/protected/json/verify/1234567/142222" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
レスポンス
{
    "message": "Token is valid.",
    "token": "is valid",
    "success": "true",
    "device": {
        "city": "San Francisco",
        "country": "United States",
        "ip": "97.20.126.156",
        "region": "California",
        "registration_city": "San Francisco",
        "registration_country": "United States",
        "registration_ip": "97.34.234.11",
        "registration_method": "sms",
        "registration_region": "California",
        "os_type": "android",
        "last_account_recovery_at": null,
        "id": 83372911,
        "registration_date": 1490996931
    }
}

例: SMS経由で受信するトークン

SMSまたは音声通話経由でOTPトークンが配信されるとき、追加のデバイス情報は提供されません。

curl -i "http://api.authy.com/protected/json/verify/1234567/111111" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
レスポンス
{
    "message": "Token is valid.",
    "token": "is valid",
    "success": "true",
    "device": {
        "city": null,
        "country": null,
        "ip": null,
        "region": null,
        "registration_city": null,
        "registration_country": null,
        "registration_ip": null,
        "registration_method": "sms",
        "registration_region": null,
        "os_type": "sms",
        "last_account_recovery_at": null,
        "id": null,
        "registration_date": 1490996931
    }
}

例: 無効なリクエスト

curl -i "http://api.authy.com/protected/json/verify/1234567/111111" \
    -H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9"
レスポンス
{
    "success": "false",
    "errors": {
        "token":"is invalid"
    }
}

例: 未登録のエンドユーザーにはワンタイムパスワードの検証を強制する

force=trueを使用して、新規エンドユーザーに対するワンタイムパスワードの検証を強制します。 falseを使用すると、そのエンドユーザーに対するトークンの検証に成功するまで常に200を返します。

curl -i "http://api.authy.com/protected/json/verify/939393/333333" \
    -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"
    }
}

カスタム・アクション

SMSの送信にカスタムアクションを使用する場合、action=を渡してワンタイムパスワードを検証することが必要です。 追加情報については、上記のワンタイムパスワードをリクエストする配下のCustom Actionsを参照してください。

{
    "token": "is valid"
}
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.