Asynchrone Implementierung

Eine asynchrone Implementierung ähnelt sehr der synchron Methode; anstatt den Geräte-Client zu verwenden, um eine Reihe von Aufrufen zu tätigen, wird jeder Teil des Arbeitsablaufs in Webhook-Rückrufe an eine von Ihnen definierte URL gesendet.

Dieser Leitfaden erklärt, wie die stille Authentifizierung mit dem asynchronen Ansatz implementiert wird, bei dem Ihr Backend einen Callback einrichtet, um das Authentifizierungsergebnis zu erhalten.

Erstellen einer Applikation

Um zu beginnen, besuchen Sie die Seite Entwickler-Dashboard um Ihre Anwendung zu erstellen:

• Vergewissern Sie sich, dass Verify unter "Fähigkeiten" aktiviert ist.
• Konfigurieren Sie die Status-URL für den Empfang von Callback-Ereignissen.
• Erzeugen einer JWT unter Verwendung der Anwendungs-ID und des privaten Schlüssels der Anwendung.

Trigger-Verifizierung

Um den Prozess der stillen Authentifizierung zu starten, stellen Sie eine Anfrage an /verify. Im folgenden Beispiel wird die Arbeitsablauf legt fest, dass Verify zunächst versucht, die stille Authentifizierung zu verwenden. Wenn die Anfrage aus irgendeinem Grund fehlschlägt, wird auf E-Mail-OTP zurückgegriffen.

Um das Beispiel auszuführen, ersetzen Sie die folgenden Variablen im Beispielcode durch Ihre eigenen Werte:

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": "email",
         "to": "'$VERIFY_EMAIL_TO'"
      }
   ]
}'

npm install @vonage/server-sdk @vonage/verify2

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,
});

vonage.verify2.newRequest({
  brand: VERIFY_BRAND_NAME,
  workflow: [
    {
      channel: SilentAuthChannel.SILENT_AUTH,
      to: VERIFY_NUMBER,
    },
    {
      channel: Channels.EMAIL,
      to: VERIFY_TO_EMAIL,
    },
  ],
})
  .then(({requestId}) => console.log(requestId))
  .catch((err) => console.error(err));

VonageClient client = VonageClient.builder()
		.applicationId(VONAGE_APPLICATION_ID)
		.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
		.build();

VerificationResponse response = client.getVerify2Client().sendVerification(
		VerificationRequest.builder()
			.addWorkflow(new SilentAuthWorkflow(VERIFY_NUMBER))
			.addWorkflow(new EmailWorkflow(VERIFY_TO_EMAIL))
			.brand(VERIFY_BRAND_NAME).build()
);
System.out.println("Verification sent: " + response.getRequestId());

Install-Package Vonage

composer require vonage/client

pip install vonage python-dotenv

gem install vonage

client = Vonage::Client.new(
  application_id: VONAGE_APPLICATION_ID,
  private_key: VONAGE_PRIVATE_KEY
)

client.verify2.start_verification(
  brand: VERIFY_BRAND_NAME,
  workflow: [
    {
      channel: 'silent_auth',
      to: VERIFY_NUMBER
    },
    {
      channel: 'email',
      to: VERIFY_TO_EMAIL
    }
  ]
)

Antwort

Wenn die Anfrage erfolgreich ist, gibt die Antwort HTTP 200 mit dem check_url im Körper, die wir im nächsten Schritt benötigen:

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

Liegt ein Fehler in der Anfrage vor, z. B. eine falsch formatierte Telefonnummer, enthält die Antwort eine HTTP 422 Fehler wie dieser:

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

Da wir die asynchrone Implementierung verwenden, erhalten Sie parallel zur API-Antwort eine Rückruf (oder Webhook) an die in den Einstellungen Ihrer Dashboard-Anwendung angegebene URL, um Sie über den Fortschritt der Anfrage zu informieren.

Während des API-Aufrufs an /verifyführt die Verify-API interne Vorprüfungen durch. Wenn alles in Ordnung ist, enthält der Callback den folgenden Body:

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

Bis der Antrag abläuft oder storniert wird, check_url wird verwendet, um eine Überprüfung der stillen Authentifizierung durchzuführen, indem Senden der Auth-URL. Wenn Sie diesen Rückruf erhalten, müssen Sie eine

Wenn eine dieser Vorprüfungen fehlschlägt, z. B. aufgrund eines Netzwerkfehlers oder eines nicht unterstützten Operators, sieht der Callback wie folgt aus:

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

Wenn Ihr /verify Anfrage einen Rückfallkanal enthält, verwendet Verify diesen Kanal weiter, wie im folgenden Sequenzdiagramm dargestellt:

Auth URL senden

Sobald Sie die

HTTP/1.1 302 Found
Location: https://eu.api.silentauth.com/phone_check/v0.2/checks/31eaf23d-b2db-4c42-9d1d-e847e75ab330/redirect

Die Befolgung der Weiterleitungen führt entweder zu einer HTTP 200 oder HTTP 4xx Antwort je nach Ergebnis. Wenn es ein Problem mit dem Netzwerk gibt, könnten Sie eine Antwort wie diese sehen:

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

Eine vollständige Liste der möglichen Fehlercodes finden Sie in der API-Spezifikation.

Wenn die Anfrage gültig ist, erhalten Sie eine HTTP 200 Antwort mit Ihrer request_id und eine code:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "code": "si9sfG"
}

Überprüfen Sie den Verifizierungscode

Sobald der Endbenutzer den Code erhält, muss Ihre Client-Anwendung eine

Um das Beispiel auszuführen, ersetzen Sie die folgenden Variablen im Beispielcode durch Ihre eigenen Werte:

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

npm install @vonage/server-sdk

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage ({
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});

vonage.verify2.checkCode(VERIFY_REQUEST_ID, VERIFY_CODE)
  .then((status) => console.log(`The status is ${status}`),
  )
  .catch((err) => console.error(err));

VonageClient client = VonageClient.builder()
		.applicationId(VONAGE_APPLICATION_ID)
		.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
		.build();

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();
	}
}

Install-Package Vonage

composer require vonage/client

pip install vonage python-dotenv

gem install vonage

client = Vonage::Client.new(
  application_id: VONAGE_APPLICATION_ID,
  private_key: VONAGE_PRIVATE_KEY
)

client.verify2.check_code(
  request_id: VERIFY_REQUEST_ID,
  code: VERIFY_CODE
)

Wenn der Code gültig ist, erhalten Sie einen Rückruf mit dem Status completed:

{
   "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
   "status": "completed"
}

Wenn ein Fehler auftritt, wird "Ungültiger Code" angezeigt:

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

Sie erhalten dann einen letzten Rückruf mit dem Ergebnis der Prüfung. Im Erfolgsfall erhalten Sie einen Callback mit "status": "completed":

{
    "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
    "triggered_at": "2020-01-01T14:00:00.000Z",
    "type": "event",
    "channel": "silent_auth",
    "status": "completed",
}

Ist dies nicht der Fall, z. B. wenn der Benutzer abgewiesen wurde, wird dies in der status Feld:

{
    "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
    "triggered_at": "2020-01-01T14:00:00.000Z",
    "type": "event",
    "channel": "silent_auth",
    "status": "user_rejected",
}

An diesem Punkt ist die Überprüfung der stillen Authentifizierung abgeschlossen.