Autenticación

La API Verify admite dos tipos de autenticación:

• Autenticación básica
• JWT

¿Cuándo se debe utilizar la autenticación básica o JWT?

Verify V2 admite dos métodos de autenticación: la autenticación básica y la autenticación JWT Bearer. Es importante comprender las diferencias entre ambos para garantizar una migración fluida y aprovechar al máximo las capacidades de V2.

Puedes utilizar cualquiera de las dos opciones, pero no ambas a la vez. En general, recomendamos utilizar JWT al trabajar con la API Verify. Aunque la autenticación Básica es más fácil para empezar, no admite la autenticación Autenticación silenciosa canal.

Autenticación básica

La autenticación básica envía tu clave API y tu secreto API Codificado en Base64 en el Authorization encabezado. Puedes encontrar estas credenciales en tu Configuración de la API en el panel de control de Vonage.

Es la forma más sencilla de empezar a utilizar Verify V2, ya que no es necesario configurar la aplicación de Vonage y tus credenciales están disponibles de inmediato desde el Panel de Vonage.

Cómo funciona

Authorization: Basic <base64(api_key:api_secret)>

Crear el encabezado de la solicitud

• En primer lugar, concatene su Clave API y su Secreto: API_KEY:API_SECRET.
• Entonces, Codificación Base64 El resultado. Más información aquí.
• Por último, envíalo en la solicitud de la siguiente manera: Authorization: Basic BASE64_ENCODED_STRING.

Puedes hacerlo desde el código de tu aplicación; por ejemplo, en 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({ ... })
});

Ejemplo de solicitud

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

Puedes generar la cadena codificada en Base64 a partir de api_key:api_secret utilizando cualquier herramienta o biblioteca estándar de codificación Base64.

Limitaciones

Basic Auth da acceso al flujo central de peticiones de Verify V2 (enviar, comprobar, cancelar, activar siguiente flujo de trabajo), pero hay dos limitaciones importantes:

• No se admiten callbacks/webhooks. Para recibir las llamadas de retorno de eventos o resúmenes, es necesario disponer de autenticación JWT Bearer, además de una aplicación de Vonage configurada con una URL de estado.
• No se admite el uso de ACL (lista de control de acceso). Los tokens JWT le permiten ampliar los permisos a puntos finales de API específicos, lo que no es posible con Basic Auth.

Dadas estas limitaciones, la autenticación básica es la más adecuada para las pruebas iniciales y las integraciones POC. Para implementaciones de producción, se recomienda encarecidamente la autenticación JWT Bearer.

JWT

A JWT (JSON Web Token) es un estándar abierto (RFC 7519) para transmitir información de forma segura entre las partes como un objeto JSON. Opcionalmente, el objeto puede cifrarse y firmarse con una clave privada/pública.

La autenticación JWT Bearer utiliza un token web JSON firmado con la clave privada de tu aplicación de Vonage. Este método permite aprovechar todas las capacidades de Verify V2, incluidas las llamadas de retorno de eventos y resúmenes, la configuración de webhooks y los tokens con ámbito de ACL.

Cómo funciona

Authorization: Bearer <JWT>

El JWT se genera usando tu ID de aplicación y clave privada, ambos obtenidos al crear una aplicación de Vonage en el panel.

Para generar un JWT, necesitarás tu application ID y private keyque se encuentran en el Aplicaciones configuración en tu Panel de control.

Hay varias formas de generar un nuevo JWT:

• Utilización de la Generador de JWT en línea.

• Utilización de la Herramienta CLI de Vonage. Es necesario facilitar la clave privada y un ID de aplicación:

Nota:

• Si utilizas uno de los servicios de Vonage SDK de servidor no es necesario generar un JWT por separado, ya que todos los SDK admiten la generación de tokens JWT.

• Si no deseas generar el JWT utilizando una herramienta o biblioteca externa, como los SDK de Vonage, puedes implementar tu propia generación de JWT. La dirección Cómo generar un JWT incluye ejemplos en JavaScript y Python que muestran cómo generar un JWT sin dependencias externas.

Una vez generado, los usuarios deberían poder utilizar el token para acceder a los puntos finales protegidos. Esto suele hacerse mediante el encabezado «Authorization», utilizando el esquema «Bearer»:

Authorization: Bearer <JWT>

Pasos de configuración de Verify V2

1. Crear una aplicación de Vonage en el Panel de Vonage.
2. Genere un par de claves pública/privada: descargue y almacene de forma segura la clave privada.
3. Activa Verify V2 para la aplicación y configura la URL de estado (punto final del webhook) para recibir las respuestas.
4. Genere un JWT firmado con su ID de aplicación y su clave privada. Puede utilizar el Generador JWTEl CLI de Vonage, o cualquier SDK de Vonage.
5. Incluye el JWT en todas las solicitudes a la API utilizando el Authorization: Bearer de cabeza.

Ejemplo de solicitud

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

Los tokens JWT tienen un tiempo máximo de vida (TTL) de 24 horas. Asegúrese de que su integración actualiza los tokens antes de que caduquen para evitar 401 Unauthorized errores.

Lo que JWT desbloquea

• Llamadas de resumen - recibir un informe de situación completo al final de cada solicitud de verificación.
• Llamadas de retorno de eventos — recibir eventos en tiempo real durante la solicitud (por ejemplo, para los canales «Silent Auth» y «WhatsApp Interactive»).
• Tokens con ámbito ACL - restrinja los permisos de token a puntos finales específicos para mejorar la seguridad.
• Configuración de webhooks - configurar verify_event_url y verify_status_url por aplicación de Vonage.

Migración de la autenticación desde Verify Legacy (V1)

Uno de los cambios fundamentales al migrar de Verify V1 a Verify V2 es la forma en que se gestiona la autenticación.

En Verify V1, la autenticación se gestionaba pasando api_key y api_secret como parámetros de consulta o en el cuerpo de la solicitud. Este método no es compatible con Verify V2.