非同期実装
はじめに
非同期実装は 同期 デバイスクライアントを使用して一連の呼び出しを行う代わりに、ワークフローのすべての部分を ウェブフック・コールバック あなたが定義したURLに送信される。
このガイドでは、非同期アプローチを使用してサイレント認証を実装する方法を説明します。 バックエンドは、認証結果を受け取るコールバックを設定します。
アプリケーションの作成
まず、次のページにアクセスする。 開発者ダッシュボード でアプリケーションを作成します：
- Capabilities」でVerifyが有効になっていることを確認する。
- コールバックイベントを受信するように Status URL を設定します。
- を生成する。 JWT アプリケーションのアプリケーションIDと秘密鍵を使用する。
トリガー検証
サイレント認証プロセスを開始するには、以下のリクエストを行う。 /verify.次の例では ワークフロー は、Verify が最初にサイレント認証を使用しようとすることを指定します。要求が何らかの理由で失敗した場合、SMS にフォールバックし、音声通話 OTP に続く。
サンプルを実行するには、サンプルコード内の以下の変数を独自の値に置き換えてください：
| 可変 | 説明 |
|---|---|
JWT | を使用して API リクエストを認証します。 JWT. |
VERIFY_BRAND_NAME | 認証メッセージでユーザーに表示される会社名またはサービス名。 |
VONAGE_APPLICATION_PRIVATE_KEY_PATH | アプリケーションの秘密鍵へのパス。 |
VONAGE_APPLICATION_ID | アプリケーションのアプリケーションID。 |
VERIFY_NUMBER | E.164形式のOTP送信先電話番号（例． +441112233447). |
Write the code
Add the following to request.sh:
curl -X POST "https://api.nexmo.com/v2/verify" \
-H "Authorization: Bearer $JWT"\
-H 'Content-Type: application/json' \
-d $'{
"brand": "'$VERIFY_BRAND_NAME'",
"workflow": [
{
"channel": "silent_auth",
"to": "'$VERIFY_NUMBER'"
},
{
"channel": "sms",
"to": "'$VERIFY_NUMBER'"
},
{
"channel": "voice",
"to": "'$VERIFY_NUMBER'"
}
]
}'Run your code
Save this file to your machine and run it:
Prerequisites
npm install @vonage/server-sdk @vonage/verify2Create a file named send-request-with-fallback.js and add the following code:
const { Vonage } = require('@vonage/server-sdk');
const { Channels, SilentAuthChannel } = require('@vonage/verify2');
const vonage = new Vonage({
applicationId: VONAGE_APPLICATION_ID,
privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});Write the code
Add the following to send-request-with-fallback.js:
vonage.verify2.newRequest({
brand: VERIFY_BRAND_NAME,
workflow: [
{
channel: SilentAuthChannel.SILENT_AUTH,
to: VERIFY_NUMBER,
},
{
channel: Channels.SMS,
to: VERIFY_NUMBER,
},
{
channel: Channels.VOICE,
to: VERIFY_NUMBER,
},
],
})
.then(({requestId}) => console.log(requestId))
.catch((err) => console.error(err));Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Create a class named SendVerificationRequestWithFallback and add the following code to the main method:
val client = Vonage {
applicationId(VONAGE_APPLICATION_ID)
privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}Write the code
Add the following to the main method of the SendVerificationRequestWithFallback class:
val response = client.verify.sendVerification(VERIFY_BRAND_NAME) {
silentAuth(VERIFY_NUMBER)
sms(VERIFY_NUMBER)
voice(VERIFY_NUMBER)
}Run your code
We can use the アプリケーション plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.verify with the package containing SendVerificationRequestWithFallback:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk:9.3.1'Create a class named SendRequestWithFallback and add the following code to the main method:
VonageClient client = VonageClient.builder()
.applicationId(VONAGE_APPLICATION_ID)
.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
.build();Write the code
Add the following to the main method of the SendRequestWithFallback class:
VerificationResponse response = client.getVerify2Client().sendVerification(
VerificationRequest.builder()
.addWorkflow(new SilentAuthWorkflow(VERIFY_NUMBER))
.addWorkflow(new SmsWorkflow(VERIFY_NUMBER))
.addWorkflow(new VoiceWorkflow(VERIFY_NUMBER))
.brand(VERIFY_BRAND_NAME).build()
);Run your code
We can use the アプリケーション plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Run the following gradle command to execute your application, replacing com.vonage.quickstart.verify2 with the package containing SendRequestWithFallback:
Prerequisites
Install-Package VonageCreate a file named StartVerificationRequestWithFallback.cs and add the following code:
using Vonage;
using Vonage.Request;
using Vonage.VerifyV2.StartVerification;
using Vonage.VerifyV2.StartVerification.Sms;
using Vonage.VerifyV2.StartVerification.Voice;
using Vonage.VerifyV2.StartVerification.SilentAuth;Add the following to StartVerificationRequestWithFallback.cs:
var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);Write the code
Add the following to StartVerificationRequestWithFallback.cs:
var request = StartVerificationRequest.Build()
.WithBrand(BRAND_NAME)
.WithWorkflow(SilentAuthWorkflow.Parse(TO_NUMBER))
.WithFallbackWorkflow(SmsWorkflow.Parse(TO_NUMBER))
.WithFallbackWorkflow(VoiceWorkflow.Parse(TO_NUMBER))
.Create();
var response = await client.VerifyV2Client.StartVerificationAsync(request);Prerequisites
composer require vonage/clientCreate a file named request.php and add the following code:
$client = new Vonage\Client(
new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);Write the code
Add the following to request.php:
$newRequest = new \Vonage\Verify2\Request\SilentAuthRequest(VERIFY_NUMBER, VERIFY_BRAND_NAME);
$smsWorkflow = new \Vonage\Verify2\VerifyObjects\VerificationWorkflow(\Vonage\Verify2\VerifyObjects\VerificationWorkflow::WORKFLOW_SMS, VERIFY_NUMBER);
$newRequest->addWorkflow($smsWorkflow);
$voiceWorkflow = new \Vonage\Verify2\VerifyObjects\VerificationWorkflow(\Vonage\Verify2\VerifyObjects\VerificationWorkflow::WORKFLOW_VOICE, VERIFY_NUMBER);
$newRequest->addWorkflow($voiceWorkflow);
$client->verify2()->startVerification($newRequest);Run your code
Save this file to your machine and run it:
Prerequisites
pip install vonage python-dotenvWrite the code
Add the following to send-request-with-fallback.py:
from vonage import Auth, Vonage
from vonage_verify import (SmsChannel, VoiceChannel, SilentAuthChannel,
StartVerificationResponse, VerifyRequest)
client = Vonage(
Auth(
application_id=VONAGE_APPLICATION_ID,
private_key=VONAGE_PRIVATE_KEY,
)
)
verify_request = VerifyRequest(
brand=VERIFY_BRAND_NAME,
workflow=[
SilentAuthChannel(to=VERIFY_NUMBER),
SmsChannel(to=VERIFY_NUMBER),
VoiceChannel(to=VERIFY_NUMBER),
],
)
response: StartVerificationResponse = client.verify.start_verification(verify_request)
pprint(response)Run your code
Save this file to your machine and run it:
Prerequisites
gem install vonageCreate a file named request.rb and add the following code:
Run your code
Save this file to your machine and run it:
応答
リクエストが成功した場合、レスポンスは以下を返す。 HTTP 200 を持つ。 check_url これは次のステップで必要になる：
HTTP/1.1 200 Ok
{
"request_id": "470b478f-334c-4f6f-b90d-b44e77ed24bf",
"check_url": "https://api-eu-4.vonage.com/v2/verify/470b478f-334c-4f6f-aaab-b4a342aed24bf/silent-auth/redirect"
}
電話番号の書式が正しくないなど、リクエストにエラーがある場合、レスポンスには HTTP 422 このようなエラーだ：
HTTP/1.1 422 Unprocessable Entity
{
"title": "Invalid params",
"detail": "The value of one or more parameters is invalid",
"instance": "b30db5a7-338e-402e-aa5a-40073a9aa07c",
"type": "https://developer.vonage.com/en/api-errors#invalid-params",
"invalid_parameters": [
{
"name": "workflow[0]",
"reason": "`to` Phone number is invalid"
}
]
}
非同期実装を使用しているので、APIレスポンスと並行して コールバック (またはWebhook）をダッシュボードアプリケーションの設定で指定されたURLに送信し、リクエストの進行状況を通知します。
へのAPI呼び出し中に /verifyの場合、Verify APIは内部的な事前チェックを行う。問題がなければ、コールバックは以下のようなボディを持つ：
HTTP/1.1 200 Ok
{
"request_id": "21a425df-04b2-43f2-990e-b19ee22e18a0",
"triggered_at": "2025-07-14T17:01:47.032Z",
"channel": "silent_auth",
"status": "action_pending",
"action": {
"type": "check",
"check_url": "https://api-eu-4.vonage.com/v2/verify/21a425df-04b2-43f2-990e-b19ee22e18a0/silent-auth/redirect"
},
"type": "event"
}
リクエストが期限切れになるか、キャンセルされるまで、 check_url によるサイレント認証チェックに使用される。 認証URLの送信.このコールバックを受け取ったら、次のように
check_url 認証しようとしているモバイル・デバイスから。 重要だ： について check_url リクエストは（Wi-Fiではなく）モバイルデータ接続を介して実行する必要があります。これを確実にするために推奨される方法は、デバイスのセルラーネットワークを介してリクエストを自動的にルーティングするVonage Client SDK（iOSまたはAndroid）を使用することです。詳しくは サイレント認証のためのWi-Fiバイパスガイド をご覧ください。
これらの事前チェックのいずれかが、例えばネットワークエラーやサポートされていないオペレーターのために失敗した場合、コールバックは次のようになる：
HTTP/1.1 200 Ok
{
request_id: "470b478f-334c-4f6f-b90d-b44e77ed24bf",
triggered_at: "2025-07-14T16:53:16.965Z",
channel: "silent_auth",
status: "failed",
type: "event"
}
もし /verify リクエストにフォールバックチャネルが含まれている場合、Verifyは以下のシーケンス図に示すように、そのチャネルの使用を継続する：
認証URLの送信
GET]リクエストを行うと、1つまたは複数の HTTP 302 リダイレクトは、ターゲット・デバイスの地域とキャリアに応じて行われる：
HTTP/1.1 302 Found
Location: https://eu.api.silentauth.com/phone_check/v0.2/checks/31eaf23d-b2db-4c42-9d1d-e847e75ab330/redirect
リダイレクトに従うと、次のいずれかになります。 HTTP 200 または HTTP 4xx のような応答が表示されるかもしれない。ネットワークに問題がある場合、次のような応答が表示されるかもしれない：
HTTP/1.1 412 Precondition Failed
Content-Type: application/json
{
"title": "Network not supported",
"detail": "Device number does not resolve to a supported Mobile Network Operator.",
"instance": "78e23b55-1633-465e-9325-6abcf186dd00",
"type": "https://developer.vonage.com/en/api-errors/verify-v2#precondition-failed"
}
潜在的なエラーコードの完全なリストは、以下のページにあります。 API仕様.
について タイムアウト管理 ベスト・プラクティス・ガイドの「ベスト・プラクティス」セクションには、このステップでネットワーク信号や通信範囲の問題などに対処するための有用な情報が記載されています。
リクエストが有効な場合は、次のメッセージが表示されます。 HTTP 200 あなたの request_id そして code:
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"code": "si9sfG"
}
注：安全な認証チェックを保証し、潜在的な中間者攻撃（man in middle attack）を軽減するために、オリジナルを保存する。 request_id と比較する。 request_id がレスポンスに返される。IDが一致しない場合は、サイレント認証チェックを中止しなければならない。詳細は サンプルアプリケーション を参照されたい。
検証コードの確認
エンドユーザーがコードを受け取ったら、クライアントアプリケーションは
/v2/verify/{request_id} エンドポイント {request_id} を、前の通話で受け取ったIDで入力してください。 サンプルを実行するには、サンプルコード内の以下の変数を独自の値に置き換えてください：
| 可変 | 説明 |
|---|---|
JWT | を使用して API リクエストを認証します。 JWT. |
VERIFY_REQUEST_ID | について request_id 前のステップで受け取った。 |
VONAGE_APPLICATION_PRIVATE_KEY_PATH | アプリケーションの秘密鍵。 |
VONAGE_APPLICATION_ID | アプリケーションのアプリケーションID。 |
VERIFY_CODE | エンドユーザーが受信した検証コード |
Write the code
Add the following to check-verification-code.sh:
curl -X POST "https://api.nexmo.com/v2/verify/$VERIFY_REQUEST_ID" \
-H "Authorization: Bearer $JWT"\
-H 'Content-Type: application/json' \
-d $'{
"code": "'$VERIFY_CODE'"
}'Run your code
Save this file to your machine and run it:
Prerequisites
npm install @vonage/server-sdkCreate a file named check-verification-code.js and add the following code:
const { Vonage } = require('@vonage/server-sdk');
const vonage = new Vonage ({
applicationId: VONAGE_APPLICATION_ID,
privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});Write the code
Add the following to check-verification-code.js:
vonage.verify2.checkCode(VERIFY_REQUEST_ID, VERIFY_CODE)
.then((status) => console.log(`The status is ${status}`),
)
.catch((err) => console.error(err));Run your code
Save this file to your machine and run it:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Create a class named CheckVerificationCode and add the following code to the main method:
val client = Vonage {
applicationId(VONAGE_APPLICATION_ID)
privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}Write the code
Add the following to the main method of the CheckVerificationCode class:
if (client.verify.request(VERIFY_REQUEST_ID).isValidVerificationCode(VERIFY_CODE)) {
println("Code matches.")
}Run your code
We can use the アプリケーション plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Run the following gradle command to execute your application, replacing com.vonage.quickstart.kt.verify with the package containing CheckVerificationCode:
Prerequisites
Add the following to build.gradle:
implementation 'com.vonage:server-sdk:9.3.1'Create a class named CheckVerificationCode and add the following code to the main method:
VonageClient client = VonageClient.builder()
.applicationId(VONAGE_APPLICATION_ID)
.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
.build();Write the code
Add the following to the main method of the CheckVerificationCode class:
try {
client.getVerify2Client().checkVerificationCode(VERIFY_REQUEST_UUID, VERIFY_CODE);
System.out.println("SUCCESS - code matches!");
}
catch (VerifyResponseException ex) {
switch (ex.getStatusCode()) {
case 400: // Code does not match
case 404: // Already verified or not found
case 409: // Workflow does not support code
case 410: // Incorrect code provided too many times
case 429: // Rate limit exceeded
default: // Unknown or internal server error (500)
ex.printStackTrace();
}
}Run your code
We can use the アプリケーション plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Run the following gradle command to execute your application, replacing com.vonage.quickstart.verify2 with the package containing CheckVerificationCode:
Prerequisites
Install-Package VonageCreate a file named VerifyCodeRequest.cs and add the following code:
using Vonage;
using Vonage.Request;Add the following to VerifyCodeRequest.cs:
var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);Write the code
Add the following to VerifyCodeRequest.cs:
var request = Vonage.VerifyV2.VerifyCode.VerifyCodeRequest.Build()
.WithRequestId(REQUEST_ID)
.WithCode(CODE)
.Create();
var response = await client.VerifyV2Client.VerifyCodeAsync(request);Prerequisites
composer require vonage/clientCreate a file named send_code.php and add the following code:
$client = new Vonage\Client(
new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);Write the code
Add the following to send_code.php:
try {
$client->verify2()->check(REQUEST_ID, CODE);
} catch (\Exception $e) {
var_dump($e->getMessage());
}Run your code
Save this file to your machine and run it:
Prerequisites
pip install vonage python-dotenvWrite the code
Add the following to check-verification-code.py:
from vonage import Auth, Vonage
from vonage_verify import CheckCodeResponse
client = Vonage(
Auth(
application_id=VONAGE_APPLICATION_ID,
private_key=VONAGE_PRIVATE_KEY,
)
)
response: CheckCodeResponse = client.verify.check_code(
request_id=VERIFY_REQUEST_ID, code=VERIFY_CODE
)
print(response)Run your code
Save this file to your machine and run it:
Prerequisites
gem install vonageCreate a file named check.rb and add the following code:
Run your code
Save this file to your machine and run it:
注：サイレント認証ワークフローのコードは、以下の場合にのみチェックできます。 かつて.
コードが有効であれば、次のステータスのコールバックを受け取ります。 completed:
{
"request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
"status": "completed"
}
エラーがある場合は「Invalid Code」と表示されます：
{
"title": "Invalid Code",
"type": "https://www.developer.vonage.com/api-errors/verify#invalid-code",
"detail": "The code you provided does not match the expected value.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
その後、チェック結果が最終的にコールバックされます。成功した場合は、コールバックに "status": "completed":
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"triggered_at": "2020-01-01T14:00:00.000Z",
"type": "event",
"channel": "silent_auth",
"status": "completed",
}
失敗した場合、例えばユーザーが拒否された場合、その旨が status フィールドにいる：
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"triggered_at": "2020-01-01T14:00:00.000Z",
"type": "event",
"channel": "silent_auth",
"status": "user_rejected",
}
この時点で、サイレント認証の検証は完了です。