Autenticación

Zentto KYC tiene dos esquemas de autenticación según quién consume la API:

Esquema	Para quién	Mecanismo
API key	Integraciones (apps / empresas), server-to-server	Header X-API-Key: zkyc_...
Cookies + CSRF	Operadores humanos en el dashboard	JWT en cookies httpOnly + CSRF double-submit

Las integraciones siempre usan API key. El esquema de cookies es exclusivo del dashboard de operadores y no se usa para integrar la API en tu backend.

Flujo del usuario

Elección del mecanismo correcto según se conecte un backend o una persona desde el dashboard.

Editable en draw.io: descarga el SVG → en draw.io: File → Import from → Device → selecciona el SVG.

Flujo técnico

Compuertas verificadas en requireApiKey, requireCsrf y requireOperator.

API key (integraciones)

Cada empresa (tenant) genera una o más API keys con prefijo zkyc_. Se envían en el header X-API-Key en cada request:

POST /v1/sessions
Host: kyc.zentto.net
X-API-Key: <KYC_API_KEY>
Content-Type: application/json

Con el SDK basta configurar apiKey en el constructor; el cliente añade el header automáticamente:

import { ZenttoKyc } from "@zentto/kyc-sdk";

const kyc = new ZenttoKyc({ apiKey: process.env.KYC_API_KEY });

Generar una API key

La creación requiere un usuario con rol operador. Se puede hacer desde el dashboard o por API:

POST /v1/keys
X-API-Key: zkyc_<operador>
Content-Type: application/json

{ "name": "backend-produccion" }

{
  "ok": true,
  "key": "<KYC_API_KEY>",
  "meta": {
    "id": 7,
    "key_prefix": "zkyc_a1b2c3",
    "name": "backend-produccion",
    "created_at": "2026-06-21T10:00:00.000Z"
  }
}

Campo	Descripción
key	API key completa. Se muestra una sola vez — guárdala de inmediato.
meta.key_prefix	Prefijo visible (los primeros 12 caracteres) para identificarla luego.

El body acepta userId (opcional, para emitir la key a otro usuario) y name (opcional, etiqueta; default "default").

Listar API keys

GET /v1/keys
X-API-Key: zkyc_...

{
  "ok": true,
  "keys": [
    {
      "id": 7,
      "key_prefix": "zkyc_a1b2c3",
      "name": "backend-produccion",
      "is_active": true,
      "rate_limit_per_day": null,
      "created_at": "2026-06-21T10:00:00.000Z",
      "last_used_at": "2026-06-21T11:30:00.000Z"
    }
  ]
}

Las keys nunca se devuelven completas en el listado; solo su prefijo.

Revocar (rotar) una API key

DELETE /v1/keys/7
X-API-Key: zkyc_...

{ "ok": true }

La revocación marca la key como inactiva (is_active = false). Para rotar: crea una nueva key, despliega el nuevo valor en tu backend y luego revoca la anterior.

Con el SDK:

await kyc.keys.create({ name: "backend-produccion" });
await kyc.keys.list();
await kyc.keys.revoke("7");

Cookies + CSRF (dashboard de operadores)

El dashboard autentica a humanos con JWT en cookies httpOnly, no para integraciones. Se documenta aquí por completitud.

Cookie	Uso
zkyc_access	Access token JWT (httpOnly)
zkyc_refresh	Refresh token JWT (httpOnly)
zkyc_csrf	Token CSRF (legible por el front, double-submit)

En las mutaciones se envía el token CSRF también como header x-csrf-token (patrón double-submit).

Método	Ruta	Descripción
GET	/v1/auth/csrf	Obtiene el token CSRF
POST	/v1/auth/login	Login { email, password } → setea cookies
POST	/v1/auth/refresh	Rota la sesión leyendo la cookie refresh
GET	/v1/auth/me	Perfil del operador autenticado
POST	/v1/auth/logout	Revoca sesiones y limpia cookies

POST /v1/auth/login
Content-Type: application/json

{ "email": "operador@empresa.com", "password": "••••••••" }

{
  "user": { "id": 1, "email": "operador@empresa.com", "role": "operator" }
}

El SDK puede incluir las cookies en requests de lectura si se instancia con withCredentials: true (y sin apiKey):

const kyc = new ZenttoKyc({ withCredentials: true });

La implementación actual del SDK no obtiene el token CSRF ni añade el header x-csrf-token. Por eso no debe usarse para mutaciones autenticadas del dashboard. El dashboard usa su cliente web, que lee zkyc_csrf y envía el header correspondiente. Las integraciones externas deben seguir usando X-API-Key desde su backend.

Buenas prácticas

• No expongas la API key en el frontend. Úsala solo server-to-server desde tu backend. Si el navegador necesita interactuar, hazlo a través de tu propio backend o con el esquema de cookies del dashboard.
• Una key por entorno/servicio (backend-produccion, backend-staging), para poder revocar de forma granular.
• Rota periódicamente: crea la nueva, despliega, revoca la vieja. La revocación es inmediata.
• Guarda la key en un secreto/variable de entorno; nunca en el repositorio.