Autenticación

Auvral autentica a tu backend con una sola llave secreta enviada en el header x-api-key:

POST /v1/sessions HTTP/1.1
x-api-key: sk_auvral_test_9Kf2mQ...
Content-Type: application/json

No hay handshake de OAuth, ni intercambio de tokens, ni endpoint de login. La llave es toda la credencial.

Las llaves son por organización y por ambiente

Tu organización tiene exactamente una llave activa por ambiente, una de sandbox y una de live. No son una lista a la que agregas; son dos espacios que rotas.

No hay ningún parámetro de ambiente en ninguna petición. La llave que usas es el ambiente en el que estás, y también decide a qué organización pertenece la sesión y a qué flujos puede referirse.

De dónde salen las llaves

Dashboard, Integraciones, Llaves de API.

• Las llaves de sandbox se pueden revelar en cualquier momento. Haz clic en Mostrar cuando necesites el valor otra vez.
• Las llaves de live se muestran exactamente una vez, en el momento en que se crean o se rotan. Auvral guarda solo un hash y no puede recuperar el valor. Si la pierdes, rota para obtener una nueva.

Una organización nueva tiene una llave de live que nunca ha sido revelada. El dashboard lo dice y te ofrece una rotación, que es segura en ese punto porque todavía nada la usa.

Rotación

Haz clic en Rotar en el ambiente que quieres reemplazar.

La rotación es inmediata y sin traslape: la llave anterior deja de funcionar en el momento en que se emite la nueva. No hay periodo de gracia ni una segunda llave activa, así que todo lo que siga enviando la llave anterior empieza a recibir 401 de inmediato.

Por eso, para una rotación en live, ordénala así:

Cuenta con una ventana corta en la que fallarán las peticiones en vuelo. Las sesiones que creaste antes de la rotación no se ven afectadas, y los usuarios a mitad de una verificación siguen normalmente.

Rota siempre que una llave pueda haber quedado expuesta: un log filtrado, un commit, alguien que deja el equipo.

Mantén la llave en tu servidor

La llave de API autentica como toda tu organización. Cualquiera que la tenga puede crear sesiones y consumir tu cuota de verificaciones.

Pertenece a exactamente un lugar: la configuración de ambiente de tu backend. Nunca debe llegar a:

• JavaScript del navegador, ni a ningún bundle que se envíe a un navegador
• el binario de una aplicación móvil
• una URL, un query string o una redirección
• un repositorio público, un log de CI o un reporte de errores

El flujo de verificación nunca la necesita. Tu backend cambia la llave por una url acotada a un solo usuario, y solo esa URL llega al navegador. Si te encuentras queriendo la llave del lado del cliente, pon POST /v1/sessions detrás de tu propia ruta autenticada y devuelve únicamente la url.

Todos los fallos devuelven el mismo 401

{ "statusCode": 401, "message": "Invalid api key", "code": "INVALID_API_KEY" }

Recibes exactamente esta respuesta cuando la llave falta, está vacía, está malformada, tiene un prefijo desconocido, no existe, fue revocada, o se está usando contra el ambiente equivocado.

Es deliberado: un mensaje más específico le diría a alguien que está sondeando tu integración cuál de sus intentos estuvo cerca.

Eso sí significa que el cuerpo de la respuesta no te dirá qué salió mal. Recorre esta lista en su lugar:

1. ¿El header está escrito x-api-key?
2. ¿El valor empieza con sk_auvral_test_ o sk_auvral_live_?
3. ¿Se rotó en el dashboard desde la última vez que la copiaste?
4. ¿Esta llave pertenece al mismo ambiente de Auvral al que apunta $AUVRAL_API_URL?
5. ¿Alguna variable de shell se está expandiendo a una cadena vacía?

La marca de tiempo Último uso en la página de llaves de API es una comprobación rápida: si nunca se actualiza, la llave nunca llegó a Auvral como esperas.

Salir a producción

Cambia una sola cosa: reemplaza sk_auvral_test_ por sk_auvral_live_. Sandbox y live responden en el mismo host, así que es el prefijo de la llave el que le dice a Auvral cuál quieres, no la URL base.

La URL base de la API en este ambiente es https://api.dev.auvral.com

Los ids de flujo son distintos por ambiente, así que revisa que estés referenciando un flujo que tu organización de live realmente tenga. Un id de flujo de sandbox enviado con una llave de live devuelve 404 Flow not found.

Todo lo demás es idéntico.

Relacionado

• Errores: la referencia completa de códigos de estado.
• Webhooks: los secretos de firma de webhooks son credenciales distintas de las llaves de API, con su propia rotación.