Autenticación silenciosa Implementación asíncrona
Introducción
Una aplicación asíncrona es muy similar a la aplicación síncrono en lugar de utilizar el cliente del dispositivo para realizar una serie de llamadas, cada parte del flujo de trabajo se incluye en el método llamadas de retorno de webhooks se redirige a una URL que tú definas.
Esta guía explica cómo implementar la autenticación silenciosa mediante el enfoque asíncrono, en el que el backend configura una llamada de retorno para recibir el resultado de la autenticación.
Crear una aplicación
Para empezar, ve a la panel de control para desarrolladores para crear su aplicación:
- Asegúrate de que la opción «Verify» esté activada en «Funcionalidades».
- Configura la URL de estado para recibir eventos de devolución de llamada.
- Generar un JWT utilizando el ID de aplicación y la clave privada de la aplicación.
Verificación de activación
Para iniciar el proceso de autenticación silenciosa, envía una solicitud a /verify. En el siguiente ejemplo, el flujo de trabajo especifica que Verify intentará utilizar primero la autenticación silenciosa. Si la solicitud falla por cualquier motivo, se volverá a SMS, seguido de una llamada de voz OTP.
Para ejecutar el ejemplo, sustituya las siguientes variables del código de ejemplo por sus propios valores:
| Variable | Descripción |
|---|---|
JWT |
Autentica la solicitud de API utilizando JWT. |
VERIFY_BRAND_NAME |
El nombre de tu empresa o servicio, que se muestra al usuario en el mensaje de verificación. |
VONAGE_APPLICATION_PRIVATE_KEY_PATH |
Ruta a la clave privada de su aplicación. |
VONAGE_APPLICATION_ID |
ID de su solicitud. |
VERIFY_NUMBER |
El número de teléfono al que se debe enviar la contraseña de un solo uso (OTP), en formato E.164 (p. ej., +441112233447). |
Escriba el código
Añada lo siguiente a 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'"
}
]
}'Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
npm install @vonage/server-sdk @vonage/verify2Crea un archivo llamado send-request-with-fallback.js y añade el siguiente código:
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,
});Escriba el código
Añada lo siguiente a 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));Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
Añada lo siguiente a build.gradle:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Crea un archivo llamado SendVerificationRequestWithFallback y añade el siguiente código al método main:
val client = Vonage {
applicationId(VONAGE_APPLICATION_ID)
privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}Escriba el código
Añada lo siguiente al método main del archivo SendVerificationRequestWithFallback:
val response = client.verify.sendVerification(VERIFY_BRAND_NAME) {
silentAuth(VERIFY_NUMBER)
sms(VERIFY_NUMBER)
voice(VERIFY_NUMBER)
}Ejecute su código
Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.kt.verify por el paquete que contiene SendVerificationRequestWithFallback:
Requisitos previos
Añada lo siguiente a build.gradle:
implementation 'com.vonage:server-sdk:9.3.1'Crea un archivo llamado SendRequestWithFallback y añade el siguiente código al método main:
VonageClient client = VonageClient.builder()
.applicationId(VONAGE_APPLICATION_ID)
.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
.build();Escriba el código
Añada lo siguiente al método main del archivo SendRequestWithFallback:
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()
);Ejecute su código
Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.verify2 por el paquete que contiene SendRequestWithFallback:
Requisitos previos
Install-Package VonageCrea un archivo llamado StartVerificationRequestWithFallback.cs y añade el siguiente código:
using Vonage;
using Vonage.Request;
using Vonage.VerifyV2.StartVerification;
using Vonage.VerifyV2.StartVerification.Sms;
using Vonage.VerifyV2.StartVerification.Voice;
using Vonage.VerifyV2.StartVerification.SilentAuth;Añada lo siguiente a StartVerificationRequestWithFallback.cs:
var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);Escriba el código
Añada lo siguiente a 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);Requisitos previos
composer require vonage/clientCrea un archivo llamado request.php y añade el siguiente código:
$client = new Vonage\Client(
new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);Escriba el código
Añada lo siguiente a 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);Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
pip install vonage python-dotenvEscriba el código
Añada lo siguiente a 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)Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
gem install vonageCrea un archivo llamado request.rb y añade el siguiente código:
client = Vonage::Client.new(
application_id: VONAGE_APPLICATION_ID,
private_key: VONAGE_PRIVATE_KEY
)Escriba el código
Añada lo siguiente a request.rb:
client.verify2.start_verification(
brand: VERIFY_BRAND_NAME,
workflow: [
{
channel: 'silent_auth',
to: VERIFY_NUMBER
},
{
channel: 'sms',
to: VERIFY_NUMBER
},
{
channel: 'voice',
to: VERIFY_NUMBER
}
]
)Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Respuesta
Si la solicitud tiene éxito, la respuesta devolverá HTTP 200 con el check_url en el cuerpo, que necesitaremos en el siguiente paso:
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"
}
Si se produce un error en la solicitud, como por ejemplo un número de teléfono con un formato incorrecto, la respuesta contendrá un HTTP 422 error como este:
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"
}
]
}
Dado que estamos utilizando la implementación asíncrona, al mismo tiempo que la respuesta de la API, recibirás un llamada de retorno (o webhook) a la URL especificada en la configuración de la aplicación de tu panel de control, para informarte del estado de la solicitud.
Durante la llamada de la API a /verifyla API Verify realiza comprobaciones previas internas. Si todo está en orden, la llamada de retorno contendrá el siguiente cuerpo:
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"
}
Hasta que la solicitud caduque o se anule, check_url se utilizará para realizar una comprobación de autenticación silenciosa mediante enviar la URL de autenticación. Al recibir esta devolución de llamada, debe realizar una solicitud GET al archivo check_url del dispositivo móvil que está intentando autenticar.
Importante: En check_url debe ejecutarse a través de una conexión de datos móviles (no Wi-Fi). La forma recomendada de asegurar esto es usar el Vonage Client SDK (iOS o Android), que enruta automáticamente la solicitud a través de la red celular del dispositivo. Consulta la Guía para la autenticación silenciosa sin pasar por la red Wi-Fi Para más información.
Si alguna de estas comprobaciones previas falla, por ejemplo, debido a un error de red o a un operador no compatible, la llamada de retorno tendrá este aspecto:
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"
}
Si su /verify incluye un canal de reserva, Verify continuará utilizando ese canal como se muestra en el siguiente diagrama de secuencia:
Enviar URL de autenticación
Una vez que hayas realizado la solicitud GET, recibirás uno o varios HTTP 302 redirecciona en función del territorio y del operador del dispositivo de destino:
HTTP/1.1 302 Found
Location: https://eu.api.silentauth.com/phone_check/v0.2/checks/31eaf23d-b2db-4c42-9d1d-e847e75ab330/redirect
Siguiendo los redireccionamientos se producirá un HTTP 200 o HTTP 4xx respuesta en función del resultado. Si hay un problema con la red, es posible que veas una respuesta como esta:
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"
}
En el siguiente documento se puede consultar una lista completa de los posibles códigos de error: Especificación API.
El Gestión del tiempo de espera de la guía de buenas prácticas contiene información útil para manejar situaciones como problemas de señal de red o de cobertura durante este paso.
Si la solicitud es válida, recibirá un HTTP 200 respuesta que contenga tu request_id y un code:
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"code": "si9sfG"
}
Nota: Para garantizar una verificación de autenticación segura y mitigar el riesgo de un posible ataque de «hombre en medio», guarda el original request_id y compárelo con el request_id devuelta en la respuesta. Si los ID no coinciden, la comprobación de autenticación silenciosa debe interrumpirse. Consulta nuestra ejemplo de solicitud para ver un ejemplo de implementación de cómo mitigar el ataque.
Introduce el código de verificación
Una vez que el usuario final recibe el código, su aplicación cliente debe enviar una solicitud POST al archivo /v2/verify/{request_id} punto final, sustituyendo {request_id} con el ID que recibió en la llamada anterior.
Para ejecutar el ejemplo, sustituya las siguientes variables del código de ejemplo por sus propios valores:
| Variable | Descripción |
|---|---|
JWT |
Autentica la solicitud de API utilizando JWT. |
VERIFY_REQUEST_ID |
El request_id recibido en el paso anterior. |
VONAGE_APPLICATION_PRIVATE_KEY_PATH |
Clave privada de su aplicación. |
VONAGE_APPLICATION_ID |
ID de su solicitud. |
VERIFY_CODE |
El código de verificación recibido por el usuario final |
Escriba el código
Añada lo siguiente a 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'"
}'Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
npm install @vonage/server-sdkCrea un archivo llamado check-verification-code.js y añade el siguiente código:
const { Vonage } = require('@vonage/server-sdk');
const vonage = new Vonage ({
applicationId: VONAGE_APPLICATION_ID,
privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});Escriba el código
Añada lo siguiente a 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));Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
Añada lo siguiente a build.gradle:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Crea un archivo llamado CheckVerificationCode y añade el siguiente código al método main:
val client = Vonage {
applicationId(VONAGE_APPLICATION_ID)
privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}Escriba el código
Añada lo siguiente al método main del archivo CheckVerificationCode:
if (client.verify.request(VERIFY_REQUEST_ID).isValidVerificationCode(VERIFY_CODE)) {
println("Code matches.")
}Ejecute su código
Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.kt.verify por el paquete que contiene CheckVerificationCode:
Requisitos previos
Añada lo siguiente a build.gradle:
implementation 'com.vonage:server-sdk:9.3.1'Crea un archivo llamado CheckVerificationCode y añade el siguiente código al método main:
VonageClient client = VonageClient.builder()
.applicationId(VONAGE_APPLICATION_ID)
.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
.build();Escriba el código
Añada lo siguiente al método main del archivo CheckVerificationCode:
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();
}
}Ejecute su código
Podemos utilizar el plugin aplicación para Gradle para simplificar la ejecución de nuestra aplicación. Actualiza tu build.gradle con lo siguiente:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Ejecute el siguiente comando gradle para ejecutar su aplicación, sustituyendo com.vonage.quickstart.verify2 por el paquete que contiene CheckVerificationCode:
Requisitos previos
Install-Package VonageCrea un archivo llamado VerifyCodeRequest.cs y añade el siguiente código:
using Vonage;
using Vonage.Request;Añada lo siguiente a VerifyCodeRequest.cs:
var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);Escriba el código
Añada lo siguiente a VerifyCodeRequest.cs:
var request = Vonage.VerifyV2.VerifyCode.VerifyCodeRequest.Build()
.WithRequestId(REQUEST_ID)
.WithCode(CODE)
.Create();
var response = await client.VerifyV2Client.VerifyCodeAsync(request);Requisitos previos
composer require vonage/clientCrea un archivo llamado send_code.php y añade el siguiente código:
$client = new Vonage\Client(
new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);Escriba el código
Añada lo siguiente a send_code.php:
try {
$client->verify2()->check(REQUEST_ID, CODE);
} catch (\Exception $e) {
var_dump($e->getMessage());
}Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
pip install vonage python-dotenvEscriba el código
Añada lo siguiente a 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)Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Requisitos previos
gem install vonageCrea un archivo llamado check.rb y añade el siguiente código:
client = Vonage::Client.new(
application_id: VONAGE_APPLICATION_ID,
private_key: VONAGE_PRIVATE_KEY
)Escriba el código
Añada lo siguiente a check.rb:
client.verify2.check_code(
request_id: VERIFY_REQUEST_ID,
code: VERIFY_CODE
)Ejecute su código
Guarde este archivo en su máquina y ejecútelo:
Nota: un código para un flujo de trabajo de autenticación silenciosa sólo puede comprobarse una vez.
Si el código es válido, recibirá una devolución de llamada con el estado completed:
{
"request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
"status": "completed"
}
O, si hay un error, verá "Código no válido":
{
"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"
}
A continuación, recibirás una respuesta final con el resultado de la comprobación. Si se ha realizado correctamente, verás una respuesta con "status": "completed":
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"triggered_at": "2020-01-01T14:00:00.000Z",
"type": "event",
"channel": "silent_auth",
"status": "completed",
}
Si no tiene éxito, por ejemplo, si el usuario ha sido rechazado, esto se indicará en la etiqueta status campo:
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"triggered_at": "2020-01-01T14:00:00.000Z",
"type": "event",
"channel": "silent_auth",
"status": "user_rejected",
}
En este momento, la verificación de la autenticación silenciosa ha finalizado.