Autenticación

Todas las requests a la API de Finova for Developers van firmadas con una API key que pasa en el header Authorization.

Authorization: Bearer finova_sk_abcdef0123456789abcdef0123456789

Formato

finova_sk_<32 caracteres hex>

• Prefix fijo: finova_sk_ (las "sk" significan secret key).
• 32 caracteres hex aleatorios → ~128 bits de entropía.
• Total: 42 caracteres.

En nuestra base de datos NUNCA guardamos el secret en plano — solo el digest SHA-256(secret + pepper). Si nuestra base se compromete, los digests no se pueden revertir a tokens funcionales.

Crear una key

Desde Finova, ve a Configuración → Finova for Developers → Generar API key. Al crearla eliges:

Campo	Detalle
Nombre	Solo para ti — recuerda dónde se va a usar (ej. Sitio público producción, ERP-OData backoffice).
Permisos	Una grilla de 4 recursos × 4 acciones. Marca solo los que realmente necesita esa integración.

Después de guardar verás el secret una sola vez con un botón de copiar. Si lo pierdes, no se puede recuperar: revoca esa key y crea otra.

Listar tus keys

En la misma página verás todas tus keys con su identificador enmascarado (ej. finova_sk_••••a2bf), permisos, último uso y estatus.

Para inspeccionar via API una key específica, no puedes — el listado es solo para la UI dentro de Finova. Esto es por diseño: una key revelada en una respuesta sería un vector de robo.

Revocar una key

Click en Revocar junto a la key. La revocación es inmediata: el próximo request que use esa key recibirá 401 invalid_key. No hay deshacer — si fue por error, crea una nueva.

Cuando revocas una key, te enviamos un email automáticamente con el detalle de qué se revocó y desde qué IP. Si recibes este email sin haber pedido tú la revocación, alguien con acceso a tu cuenta hizo la acción — cambia tu contraseña de Finova de inmediato.

Lista blanca de dominios

A nivel de cuenta (no por key) puedes definir desde qué dominios se aceptan los requests. Aplica solo a requests originados en navegadores (con header Origin o Referer):

• Lista vacía → cualquier origen puede usar las keys. Útil para integraciones server-to-server.
• Lista no vacía → el request debe traer Origin o Referer cuyo host matchee uno de los registrados, o se rechaza con 403 origin_not_allowed.

Cambia la lista desde Configuración → Finova for Developers → Dominios permitidos.

Por qué dos capas

Las keys con scope acotan qué pueden hacer. El whitelist de dominios acota desde dónde se pueden usar. Combinarlos:

• Una key read-products, read-customers montada en tu sitio público con whitelist ["miempresa.com"] solo puede leer productos/clientes desde tu sitio. Si te roban el secret y lo prueban desde otro origen, falla en el preflight de CORS.
• Una key con CRUD completo sin whitelist sirve para tu ERP backoffice. Manten ese secret en un secret manager y no en código cliente.

Rotación

Rotar es simple:

1. Crea la key nueva con los mismos permisos.
2. Actualiza tu integración para usarla.
3. Verifica que el último uso registrado de la key vieja sea anterior al rollout.
4. Revoca la vieja.

Cuando entremos a un esquema de keys con expiración automática (post-Fase 1), te avisaremos.

Auditoría

Cada autenticación, exitosa o fallida, queda en nuestros logs estructurados:

• IP y user-agent
• Identificador enmascarado de la key (prefix + last_four)
• Origin/Referer
• Endpoint y método

Si sospechas que tu key fue comprometida, puedes pedirnos el log filtrado por su identificador. NO almacenamos el secret completo en ninguno de nuestros logs.