Autenticacion

Veridia usa autenticacion con bearer token. Cada request a la API (excepto /health) necesita un header Authorization:

Authorization: Bearer qv_pub_FJJWXMA2RN2XPRDK6YJX4KTVD0XSQHW9

Tipos de keys

Hay dos clases de keys, con diferentes propiedades de seguridad:

Tipo	Prefijo	Usar desde	Permisos
Publishable	qv_pub_*	Browser, widget, cliente publico	Iniciar verificaciones, enviar capturas
Secret	qv_sec_*	Solo server-side	Todos los scopes publishable + obtener veredictos + desencriptar webhook secrets

La publishable key es segura para exponer en tu HTML / SPA bundle. Esta atada a un tenant especifico y a una lista de allowed origins — no puede ser usada desde un dominio que no fue explicitamente whitelisted.

La secret key nunca es segura para exponer. Puede obtener veredictos para cualquier verificacion en tu tenant. Tratala como una password de base de datos.

Environments

Cada tenant tiene dos sets paralelos de keys:

Environment	Publishable	Secret	Comportamiento
Test	qv_pub_test_*	qv_sec_test_*	Gratis, pipeline ML real, sin impacto en facturacion
Live	qv_pub_*	qv_sec_*	Facturacion real, verificaciones reales

Workflow recomendado:

1. Construis e integras contra test keys
2. Corres verificaciones de prueba hasta que estes contento con el flow
3. Cambias a live keys en produccion

Las verificaciones de test se guardan en la misma DB que las live, pero con un flag que las excluye de tu facturacion y estadisticas.

Whitelist de dominios (publishable keys)

Cada publishable key tiene una lista de allowed origins. El widget rechaza cargar en cualquier dominio que no este en la lista.

Configura esto en tu dashboard en API keys → Edit → Allowed origins:

https://tuapp.com
https://staging.tuapp.com
http://localhost:3000

Wildcards como *.tuapp.com estan soportados.

:::warning Localhost durante desarrollo Tenes que agregar explicitamente http://localhost:PORT a los allowed origins para testing local. El widget rechaza por defecto — esto previene que keys leaked sean usadas por atacantes corriendo su propio localhost. :::

Usando la secret key

Ejemplos server-side:

curl

curl -X GET https://api.xxuxe.online/v1/verify/vf_AG07CDWRRFQV4T05ZXG2 \
  -H "Authorization: Bearer qv_sec_TU_SECRET"

JavaScript / Node.js

const response = await fetch('https://api.xxuxe.online/v1/verify/' + id, {
  headers: {
    'Authorization': `Bearer ${process.env.VERIDIA_SECRET_KEY}`,
  },
});
const data = await response.json();

Python

import os, requests

response = requests.get(
    f"https://api.xxuxe.online/v1/verify/{verification_id}",
    headers={"Authorization": f"Bearer {os.environ['VERIDIA_SECRET_KEY']}"},
)
data = response.json()

PHP

<?php
$ch = curl_init("https://api.xxuxe.online/v1/verify/$verificationId");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $_ENV['VERIDIA_SECRET_KEY'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Rotacion de keys

Las keys pueden rotarse en cualquier momento desde el dashboard:

1. Anda a API keys
2. Haces click en Rotate sobre la key que queres reemplazar
3. La nueva key se muestra una vez — copiala
4. Actualizas tu codigo / environment
5. La key vieja sigue funcionando por 15 minutos para darte una ventana de deployment
6. Despues de 15 minutos, la key vieja queda permanentemente invalida

Para revocacion de emergencia (sospecha de leak), usa Revoke en su lugar — mata la key inmediatamente.

Best practices

• Nunca commitees secret keys al source control. Usa variables de entorno o un secrets manager
• Usa keys separadas para test y live — nunca uses una live key en staging
• Limita los allowed origins solo a los dominios que los necesiten
• Rota las keys cada trimestre como practica de higiene
• Loguea el request ID de las responses de la API — hace que los tickets de soporte se resuelvan 10x mas rapido
• Para llamadas server-side, siempre usa la secret key — nunca la publishable

Errores de autenticacion

HTTP	Error code	Que significa
401	unauthorized	Header Authorization faltante o malformado
401	invalid_key	La key no existe, expiro, o fue revocada
403	origin_not_allowed	Request desde un dominio que no esta en allowed origins
403	wrong_environment	Test key usada contra endpoint live o viceversa
429	rate_limited	Demasiadas requests — mira Rate limits

Mira Errores para el catalogo completo de errores.

Que sigue

• POST /v1/verify/init — iniciar una verificacion
• Errores — referencia completa de codigos de error
• Rate limits — limites y cuotas