Autenticação

Verify oferece suporte a dois tipos de autenticação:

• Autenticação básica
• JWT

Quando se deve usar a autenticação básica ou o JWT?

A versão V2 do Verify oferece suporte a dois métodos de autenticação: autenticação básica e autenticação JWT Bearer. É importante compreender as diferenças entre eles para garantir uma migração tranquila e aproveitar ao máximo os recursos da versão V2.

Você pode usar qualquer uma das opções, mas não as duas ao mesmo tempo. Em geral, recomendamos o uso do JWT autenticação ao trabalhar com a API Verify. Embora a autenticação básica seja mais fácil para quem está começando, ela não oferece suporte à Autenticação silenciosa canal.

Autenticação básica

A autenticação básica envia sua chave de API e seu segredo de API Codificado em Base64 no Authorization cabeçalho. Você pode encontrar essas credenciais em seu Configurações da API no Painel da Vonage.

Essa é a maneira mais simples de começar a usar o Verify V2, já que não é necessária nenhuma configuração do aplicativo da Vonage, e suas credenciais ficam imediatamente disponíveis no Painel do Vonage.

Como funciona

Authorization: Basic <base64(api_key:api_secret)>

Criar o cabeçalho da solicitação

• Primeiro, concatene sua chave de API e seu segredo: API_KEY:API_SECRET.
• Então, Codificação Base64 o resultado. Saiba mais aqui.
• Por fim, envie-o na solicitação da seguinte forma: Authorization: Basic BASE64_ENCODED_STRING.

Você pode fazer isso no código do seu aplicativo — por exemplo, em JavaScript:

const credentials = btoa('YOUR_API_KEY:YOUR_API_SECRET');

const response = await fetch('https://api-eu.vonage.com/v2/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + credentials
  },
  body: JSON.stringify({ ... })
});

Exemplo de solicitação

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

Você pode gerar a string codificada em Base64 a partir de api_key:api_secret utilizando qualquer ferramenta ou biblioteca padrão de codificação Base64.

Limitações

A autenticação básica permite acessar o fluxo principal de solicitações do Verify V2 (enviar, verificar, cancelar, acionar o próximo fluxo de trabalho), mas há duas limitações importantes:

• Callbacks/webhooks não são suportados. Para receber callbacks de eventos ou resumos, é necessária a autenticação JWT Bearer, além de uma Application da Vonage configurada com uma URL de status.
• O suporte a ACL (Lista de Controle de Acesso) não está disponível. Os tokens JWT permitem delimitar as permissões a pontos de extremidade específicos da API, o que não é possível com a autenticação básica.

Dadas essas limitações, a autenticação Basic Auth é mais adequada para testes iniciais e integrações de POC. Para implantações em produção, recomenda-se fortemente a autenticação JWT Bearer.

JWT

A JWT (JSON Web Token) é um padrão aberto (RFC 7519) para transmitir informações de forma segura entre as partes na forma de um objeto JSON. O objeto pode, opcionalmente, ser criptografado e assinado com uma chave privada/pública.

A autenticação JWT Bearer utiliza um JSON Web Token assinado com a chave privada do seu aplicativo Vonage. Esse método permite acessar todos os recursos do Verify V2, incluindo callbacks de eventos e resumos, configuração de webhooks e tokens com escopo de ACL.

Como funciona

Authorization: Bearer <JWT>

O JWT é gerado usando seu ID de aplicativo e sua chave privada, ambos obtidos ao criar uma aplicação da Vonage no painel de controle.

Para gerar um JWT, você precisará do seu application ID e private key, ambos disponíveis no Applications configurações no seu Painel de controle.

Existem várias maneiras de gerar um novo JWT:

• Usando o Gerador online de JWT.

• Usando o Ferramenta CLI da Vonage. É necessário fornecer a chave privada e um ID de aplicativo:

Observação:

• Se você estiver usando um dos serviços da Vonage SDKs de servidor Você não precisa gerar um JWT separadamente, pois todos os SDKs oferecem suporte à geração de tokens JWT.

• Se você não quiser gerar o JWT usando uma ferramenta ou biblioteca externa, como os SDKs da Vonage, poderá implementar sua própria geração de JWT. O Como gerar um JWT A postagem do blog inclui exemplos em JavaScript e Python que mostram como gerar um JWT sem dependências externas.

Uma vez gerado, os usuários devem poder utilizar o token para acessar endpoints protegidos. Isso geralmente é feito por meio do cabeçalho Authorization, utilizando o esquema Bearer:

Authorization: Bearer <JWT>

Etapas de configuração do Verify V2

1. Crie uma aplicação da Vonage no Painel do Vonage.
2. Gere um par de chaves pública/privada — baixe e armazene a chave privada com segurança.
3. Ative o Verify V2 para o aplicativo e configure a URL de status (ponto de extremidade do webhook) para receber chamadas de retorno.
4. Gere um JWT assinado com o ID do seu aplicativo e a chave privada. Você pode usar o Gerador de JWT, o CLI da Vonage, ou qualquer SDK da Vonage.
5. Inclua o JWT em todas as solicitações de API usando o Authorization: Bearer cabeçalho.

Exemplo de solicitação

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

Os tokens JWT têm um tempo de vida máximo (TTL) de 24 horas. Certifique-se de que sua integração atualize os tokens antes do vencimento para evitar 401 Unauthorized erros.

O que o JWT possibilita

• Callbacks de resumo — receber um relatório completo sobre o andamento ao final de cada solicitação de verificação.
• Callbacks de eventos — receber eventos em tempo real durante a solicitação (por exemplo, para os canais “Silent Auth” e “WhatsApp Interactive”).
• Tokens com escopo ACL — restringir as permissões dos tokens a endpoints específicos para aumentar a segurança.
• Configuração do webhook — configurar verify_event_url e verify_status_url conforme o aplicativo da Vonage.

Migração da autenticação do Verify Legacy (V1)

Uma das principais mudanças na migração do Verify V1 para o Verify V2 é a forma como a autenticação é tratada.

No Verify V1, a autenticação era feita por meio da passagem de api_key e api_secret como parâmetros de consulta ou no corpo da solicitação. Esse método não é compatível com o Verify V2.