Autenticación

Verify API 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: Autenticación básica y autenticación JWT Bearer. Comprender las diferencias entre ambos es importante para garantizar una migración fluida y aprovechar al máximo las capacidades de V2.

Puede 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 su clave y secreto de API Codificado en Base64 en el Authorization cabecera. Puede encontrar estas credenciales en Configuración de la API en el panel de control de Vonage.

Es la forma más simple de comenzar a usar Verify V2, ya que no se requiere la configuración de la aplicación de Vonage y tus credenciales están disponibles de inmediato en la aplicación Panel de Vonage.

Cómo funciona

Authorization: Basic <base64(api_key:api_secret)>

Crear la cabecera 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íelo en la solicitud como Authorization: Basic BASE64_ENCODED_STRING.

Puede hacerlo dentro del código de su 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" }
    ]
  }'

Puede 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. La recepción de devoluciones de llamada de eventos o resúmenes requiere la autenticación del portador JWT, junto con una aplicación de Vonage configurada con una URL de estado.
• El soporte ACL (Access Control List) no está disponible. 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 de portador JWT usa un token web JSON firmado con la clave privada de tu aplicación de Vonage. Este método desbloquea todas las capacidades de Verify V2, incluidas las devoluciones de llamada de eventos y resúmenes, la configuración de webhook y los tokens con 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á su application ID y private keyque se encuentran en el Aplicaciones configuración en su Cuadro de mandos.

Hay varias formas de generar un nuevo JWT:

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

• Utilización de la Herramienta CLI de Vonage. Se debe proporcionar la clave privada y un ID de aplicación:

Tenga en cuenta lo siguiente:

• Si utilizas uno de los 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 deben poder utilizar el token para acceder a los extremos protegidos. Esto suele hacerse mediante la cabecera Authorization utilizando el esquema Bearer:

Authorization: Bearer <JWT>

Pasos para configurar Verify V2

1. Crear una aplicación de Vonage en la sección Panel de Vonage.
2. Genere un par de claves pública/privada: descargue y almacene de forma segura la clave privada.
3. Active Verify V2 para la aplicación y configure la URL de estado (punto final de webhook) para recibir devoluciones de llamada.
4. Genere un JWT firmado con su ID de aplicación y su clave privada. Puede utilizar el Generador JWTEl CLI de Vonageo cualquier SDK de Vonage.
5. Incluya el JWT en todas las solicitudes de API utilizando la directiva 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.
• Reactivación de eventos - recibir eventos en tiempo real durante la solicitud (por ejemplo, para los canales Silent Auth y WhatsApp Interactive).
• Fichas 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 clave al migrar de Verify V1 a Verify V2 es cómo 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.