Implementação assíncrona de autenticação silenciosa
Introdução
Uma implementação assíncrona é muito semelhante à síncrono método; em vez de usar o cliente do dispositivo para fazer uma série de chamadas, cada etapa do fluxo de trabalho é incluída em retornos de chamada de webhook enviado para uma URL definida por você.
Este guia explica como implementar a autenticação silenciosa usando a abordagem assíncrona, na qual seu backend configura um callback para receber o resultado da autenticação.
Criar um aplicativo
Para começar, acesse o painel do desenvolvedor Para criar seu aplicativo:
- Certifique-se de que a opção “Verify” esteja ativada na seção “Recursos”.
- Configure a URL de status para receber eventos de retorno de chamada.
- Gerar um JWT utilizando o ID do aplicativo e a chave privada do aplicativo.
Verificação do gatilho
Para iniciar o processo de autenticação silenciosa, envie uma solicitação para /verify. No exemplo a seguir, o fluxo de trabalho especifica que o Verify tentará, em primeiro lugar, utilizar a autenticação silenciosa. Se a solicitação falhar por qualquer motivo, ele recorrerá então ao SMS, seguido por uma senha de uso único (OTP) por chamada de voz.
Para executar o exemplo, substitua as seguintes variáveis no código de exemplo pelos seus próprios valores:
| Variável | Descrição |
|---|---|
JWT |
Autentica a solicitação da API usando JWT. |
VERIFY_BRAND_NAME |
O nome da sua empresa ou serviço, exibido ao usuário na mensagem de verificação. |
VONAGE_APPLICATION_PRIVATE_KEY_PATH |
Caminho para a chave privada do seu aplicativo. |
VONAGE_APPLICATION_ID |
ID do seu aplicativo. |
VERIFY_NUMBER |
O número de telefone para o qual a OTP deve ser enviada, no formato E.164 (por exemplo, +441112233447). |
Escreva o código
Adicione o seguinte ao arquivo ` 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'"
}
]
}'Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
npm install @vonage/server-sdk @vonage/verify2Crie um arquivo chamado ` send-request-with-fallback.js ` e insira o seguinte 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,
});Escreva o código
Adicione o seguinte ao arquivo ` 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));Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
Adicione o seguinte ao arquivo ` build.gradle`:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Crie um arquivo chamado ` SendVerificationRequestWithFallback ` e adicione o código a seguir ao método ` main `:
val client = Vonage {
applicationId(VONAGE_APPLICATION_ID)
privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}Escreva o código
Adicione o seguinte ao método ` main ` do arquivo ` SendVerificationRequestWithFallback `:
val response = client.verify.sendVerification(VERIFY_BRAND_NAME) {
silentAuth(VERIFY_NUMBER)
sms(VERIFY_NUMBER)
voice(VERIFY_NUMBER)
}Execute seu código
Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.kt.verify ` pelo pacote que contém ` SendVerificationRequestWithFallback`:
Pré-requisitos
Adicione o seguinte ao arquivo ` build.gradle`:
implementation 'com.vonage:server-sdk:9.3.1'Crie um arquivo chamado ` SendRequestWithFallback ` e adicione o código a seguir ao método ` main `:
VonageClient client = VonageClient.builder()
.applicationId(VONAGE_APPLICATION_ID)
.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
.build();Escreva o código
Adicione o seguinte ao método ` main ` do arquivo ` 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()
);Execute seu código
Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.verify2 ` pelo pacote que contém ` SendRequestWithFallback`:
Pré-requisitos
Install-Package VonageCrie um arquivo chamado ` StartVerificationRequestWithFallback.cs ` e insira o seguinte 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;Adicione o seguinte ao arquivo ` StartVerificationRequestWithFallback.cs`:
var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);Escreva o código
Adicione o seguinte ao arquivo ` 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);Pré-requisitos
composer require vonage/clientCrie um arquivo chamado ` request.php ` e insira o seguinte código:
$client = new Vonage\Client(
new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);Escreva o código
Adicione o seguinte ao arquivo ` 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);Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
pip install vonage python-dotenvEscreva o código
Adicione o seguinte ao arquivo ` 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)Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
gem install vonageCrie um arquivo chamado ` request.rb ` e insira o seguinte código:
client = Vonage::Client.new(
application_id: VONAGE_APPLICATION_ID,
private_key: VONAGE_PRIVATE_KEY
)Escreva o código
Adicione o seguinte ao arquivo ` 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
}
]
)Execute seu código
Salve este arquivo no seu computador e execute-o:
Resposta
Se a solicitação for bem-sucedida, a resposta retornará HTTP 200 com o check_url no corpo do texto, que vamos precisar na próxima etapa:
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"
}
Se houver um erro na solicitação, como um número de telefone com formatação incorreta, a resposta conterá um HTTP 422 erro 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"
}
]
}
Como estamos usando a implementação assíncrona, paralelamente à resposta da API, você receberá um chamada de retorno (ou webhook) para a URL especificada nas configurações do seu painel de controle, informando-lhe sobre o andamento da solicitação.
Durante a chamada da API para /verify, a API Verify realiza verificações prévias internas. Se tudo estiver em ordem, a chamada de retorno conterá o seguinte corpo:
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"
}
Até que a solicitação expire ou seja cancelada, check_url será usado para realizar uma verificação de autenticação silenciosa por envio da URL de autenticação. Ao receber essa chamada de retorno, você deve fazer uma solicitação GET para o check_url a partir do dispositivo móvel no qual você está tentando se autenticar.
Importante: O check_url A solicitação deve ser executada por meio de uma conexão de dados móveis (não por Wi-Fi). A maneira recomendada de garantir isso é usar o Vonage Client SDK (iOS ou Android), que encaminha automaticamente a solicitação pela rede celular do dispositivo. Consulte o Guia para autenticação silenciosa sem Wi-Fi para mais detalhes.
Se alguma dessas verificações prévias falhar, por exemplo, devido a um erro de rede ou a uma operadora não compatível, a chamada de retorno ficará assim:
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"
}
Se o seu /verify Se a solicitação incluir um canal alternativo, o Verify continuará usando esse canal, conforme mostrado no diagrama de sequência a seguir:
Enviar URL de autenticação
Depois de enviar a solicitação GET, você receberá uma ou mais HTTP 302 redirecionamentos dependendo da região e da operadora do 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
Seguir os redirecionamentos resultará em: HTTP 200 ou HTTP 4xx resposta dependendo do resultado. Se houver algum problema com a rede, você poderá ver uma resposta 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"
}
Uma lista completa dos possíveis códigos de erro pode ser encontrada no Especificação da API.
O Gerenciamento de tempo limite Essa seção do guia de Melhores Práticas contém informações úteis para lidar com situações como problemas de sinal ou cobertura de rede durante esta etapa.
Se a solicitação for válida, você receberá um HTTP 200 resposta contendo o seu request_id e um code:
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"code": "si9sfG"
}
Observação: Para garantir uma verificação de autenticação segura e mitigar o risco de um possível ataque do tipo “man-in-the-middle”, armazene o original request_id e comparar com o request_id retornados na resposta. Se os IDs não corresponderem, a verificação de autenticação silenciosa deve ser interrompida. Consulte nosso exemplo de inscrição para ver um exemplo de implementação de como mitigar esse ataque.
Verifique o código de verificação
Assim que o usuário final receber o código, seu aplicativo cliente deve enviar uma solicitação POST para o /v2/verify/{request_id} ponto final, substituindo {request_id} com o número de identificação que você recebeu na ligação anterior.
Para executar o exemplo, substitua as seguintes variáveis no código de exemplo pelos seus próprios valores:
| Variável | Descrição |
|---|---|
JWT |
Autentica a solicitação da API usando JWT. |
VERIFY_REQUEST_ID |
O request_id recebido na etapa anterior. |
VONAGE_APPLICATION_PRIVATE_KEY_PATH |
Chave privada do seu aplicativo. |
VONAGE_APPLICATION_ID |
ID do seu aplicativo. |
VERIFY_CODE |
O código de verificação recebido pelo usuário final |
Escreva o código
Adicione o seguinte ao arquivo ` 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'"
}'Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
npm install @vonage/server-sdkCrie um arquivo chamado ` check-verification-code.js ` e insira o seguinte código:
const { Vonage } = require('@vonage/server-sdk');
const vonage = new Vonage ({
applicationId: VONAGE_APPLICATION_ID,
privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});Escreva o código
Adicione o seguinte ao arquivo ` 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));Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
Adicione o seguinte ao arquivo ` build.gradle`:
implementation 'com.vonage:server-sdk-kotlin:2.1.1'Crie um arquivo chamado ` CheckVerificationCode ` e adicione o código a seguir ao método ` main `:
val client = Vonage {
applicationId(VONAGE_APPLICATION_ID)
privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}Escreva o código
Adicione o seguinte ao método ` main ` do arquivo ` CheckVerificationCode `:
if (client.verify.request(VERIFY_REQUEST_ID).isValidVerificationCode(VERIFY_CODE)) {
println("Code matches.")
}Execute seu código
Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.kt.verify ` pelo pacote que contém ` CheckVerificationCode`:
Pré-requisitos
Adicione o seguinte ao arquivo ` build.gradle`:
implementation 'com.vonage:server-sdk:9.3.1'Crie um arquivo chamado ` CheckVerificationCode ` e adicione o código a seguir ao método ` main `:
VonageClient client = VonageClient.builder()
.applicationId(VONAGE_APPLICATION_ID)
.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
.build();Escreva o código
Adicione o seguinte ao método ` main ` do arquivo ` 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();
}
}Execute seu código
Podemos usar o plugin “ aplicativo ” para o Gradle a fim de simplificar a execução do nosso aplicativo. Atualize seu arquivo ` build.gradle ` com o seguinte:
apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''Execute o seguinte comando ` gradle ` para rodar seu aplicativo, substituindo ` com.vonage.quickstart.verify2 ` pelo pacote que contém ` CheckVerificationCode`:
Pré-requisitos
Install-Package VonageCrie um arquivo chamado ` VerifyCodeRequest.cs ` e insira o seguinte código:
using Vonage;
using Vonage.Request;Adicione o seguinte ao arquivo ` VerifyCodeRequest.cs`:
var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_APPLICATION_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);Escreva o código
Adicione o seguinte ao arquivo ` VerifyCodeRequest.cs`:
var request = Vonage.VerifyV2.VerifyCode.VerifyCodeRequest.Build()
.WithRequestId(REQUEST_ID)
.WithCode(CODE)
.Create();
var response = await client.VerifyV2Client.VerifyCodeAsync(request);Pré-requisitos
composer require vonage/clientCrie um arquivo chamado ` send_code.php ` e insira o seguinte código:
$client = new Vonage\Client(
new Vonage\Client\Credentials\Keypair(VONAGE_APPLICATION_PRIVATE_KEY_PATH, VONAGE_APPLICATION_ID),
);Escreva o código
Adicione o seguinte ao arquivo ` send_code.php`:
try {
$client->verify2()->check(REQUEST_ID, CODE);
} catch (\Exception $e) {
var_dump($e->getMessage());
}Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
pip install vonage python-dotenvEscreva o código
Adicione o seguinte ao arquivo ` 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)Execute seu código
Salve este arquivo no seu computador e execute-o:
Pré-requisitos
gem install vonageCrie um arquivo chamado ` check.rb ` e insira o seguinte código:
client = Vonage::Client.new(
application_id: VONAGE_APPLICATION_ID,
private_key: VONAGE_PRIVATE_KEY
)Escreva o código
Adicione o seguinte ao arquivo ` check.rb`:
client.verify2.check_code(
request_id: VERIFY_REQUEST_ID,
code: VERIFY_CODE
)Execute seu código
Salve este arquivo no seu computador e execute-o:
Observação: um código para um fluxo de trabalho de autenticação silenciosa só pode ser verificado uma vez.
Se o código for válido, você receberá uma resposta com o status completed:
{
"request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
"status": "completed"
}
Ou, se houver um erro, você verá “Código invá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"
}
Em seguida, você receberá uma resposta final com o resultado da verificação. Se for aprovado, você receberá uma resposta com "status": "completed":
{
"request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
"triggered_at": "2020-01-01T14:00:00.000Z",
"type": "event",
"channel": "silent_auth",
"status": "completed",
}
Caso não seja bem-sucedido, por exemplo, se o usuário tiver sido rejeitado, isso será indicado no 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",
}
Neste momento, a verificação da autenticação silenciosa está concluída.