Autenticación

Cada solicitud a la API de Certivant se autentica con una clave de API: un token Bearer de larga duración limitado a una única organización. Las sesiones y las cookies son para el panel; la API nunca las usa.

Formato del encabezado

Authorization: Bearer ck_live_NjV3aXJWN0RpZ2tRZ1JLWEcxc1V2eEgwUjg...

• El nombre del encabezado es Authorization.
• El esquema es Bearer (un espacio y luego la clave).
• La clave empieza por ck_live_ (producción) o ck_test_ (pruebas). Las claves antiguas que empiezan por kyk_ siguen funcionando sin cambios.

Toda respuesta de un endpoint autenticado con clave incluye X-Certivant-Environment: live|test. Las claves de prueba solo etiquetan el uso; no aíslan los datos (consulte Claves de producción frente a claves de prueba).

Si la clave falta, es desconocida, ha sido revocada, ha caducado o se ha rotado, Certivant responde con HTTP 401 y error.code = "UNAUTHORIZED". error.reason es un subcódigo estable:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "reason": "api_key_expired",
    "message": "This API key has expired. Create or rotate a key."
  }
}

De dónde salen las claves

Las claves de API se crean en el panel, en KYC → Desarrollador. Debe ser Propietario o Administrador de la organización. La clave se muestra solo una vez, justo después de crearla: Certivant almacena un hash SHA-256, así que no podemos volver a mostrarla. Si la pierde, revóquela y cree una nueva.

El panel muestra cada clave (por su prefijo de 8 caracteres) junto con sus ámbitos, la fecha y hora de último uso y el número de usos. Puede revocar una clave en cualquier momento; la revocación es inmediata e irreversible.

Ámbitos

Los ámbitos son acumulativos. Puede conceder cualquier subconjunto al crear una clave. Una solicitud a un endpoint cuyo ámbito requerido no tenga la clave devuelve HTTP 403 con error.code = "FORBIDDEN" y error.reason = "insufficient_scope"; el mensaje enumera todos los ámbitos que habrían sido aceptados.

Ámbitos estándar

Ámbitos por recurso

Para aplicar el principio de mínimo privilegio, puede conceder ámbitos <recurso>:<acción> en su lugar. Cada uno se acepta en los endpoints de su propio recurso además del ámbito estándar correspondiente, y nunca se extiende más allá de ese recurso.

Ejemplos: forms:write permite a una clave hacer POST /v1/kyc/forms/:formId/send, pero no crear solicitudes de verificación; verifications:read + analytics:read es una clave de solo lectura para un panel. <recurso>:manage incluye cualquier otra acción sobre ese recurso.

Restricciones

Además de los ámbitos, una clave puede restringirse al crearla o editarla:

• Formularios: la clave solo puede usar los formularios que elija y solo puede acceder a verificaciones creadas a través de ellos. Consulte Restricción de formularios.
• Workflows: la clave solo puede activar los flujos de automatización (por nombre) que elija. Consulte Restricción de workflows.
• Lista de IP permitidas: direcciones IPv4/IPv6 y rangos CIDR (203.0.113.7, 198.51.100.0/24, 2001:db8::/32). Una solicitud desde cualquier otra dirección, o cuya dirección no pueda determinarse, se rechaza con 403 ip_not_allowed.
• Caducidad: después de expiresAt, la clave devuelve 401 api_key_expired.

Todas las restricciones están vacías (sin restricción) por defecto, y las claves existentes no tienen ninguna. Las claves creadas antes de que existieran las restricciones (kyk_…) y los tokens del conector nunca tienen restricciones.

Restricción de formularios

Una clave restringida a los formularios X e Y queda confinada a esos formularios y a las verificaciones creadas a través de ellos. Una verificación se considera "creada a través de un formulario" cuando se envió con POST /v1/kyc/forms/:formId/send (por cualquier clave o desde el panel), se envió mediante el enlace público del formulario o se creó con POST /v1/kyc/requests y un formId.

Una renovación, o una verificación de UBO generada por una verificación empresarial, pertenece al mismo formulario que la verificación de origen.

Restricción de workflows

Certivant no tiene ningún endpoint que nombre un workflow, así que esta restricción no produce un 403 en ninguna llamada. Controla qué workflows de automatización pueden ejecutarse para las verificaciones que crea la clave:

• Cada verificación creada por la clave (POST /v1/kyc/requests, /requests/batch, POST /v1/kyc/forms/:formId/send, POST /v1/kyc/conferences con un solicitante en línea) registra la clave de la que procede.
• A partir de ese momento, para esa verificación únicamente, pueden ejecutarse los workflows cuyo nombre figure en la lista de la clave, sea cual sea el evento que los dispare: el solicitante que envía el formulario, una decisión, un revisor, un webhook o la propia clave. Las ejecuciones de otros workflows que coincidan con el evento se omiten, y también se omite un workflow que otro workflow inicie con un paso Trigger workflow.
• La lista actual de la clave se aplica mientras la clave exista, así que ampliar o levantar la restricción surte efecto de inmediato en las verificaciones en curso. Si la clave se elimina, sigue aplicándose la lista que tenía cuando creó la verificación.
• Las verificaciones creadas desde el panel, por un solicitante en un formulario público, o por una clave sin restricción de workflows no se ven afectadas, como tampoco ningún otro disparador (programaciones, otras verificaciones).
• Una renovación, y las verificaciones de UBO de una empresa, heredan la restricción de la verificación de origen.

El motivo de error workflow_not_allowed está reservado para endpoints que reciben un workflow por nombre; hoy no existe ninguno.

Claves de producción frente a claves de prueba

Las claves ck_live_… son para producción y las ck_test_… para desarrollo e integración continua (CI). El entorno es una etiqueta, no un sandbox: las respuestas incluyen X-Certivant-Environment, el panel muestra la insignia y las entradas de auditoría registran el prefijo de la clave, pero una clave de prueba lee y escribe los mismos datos que una clave de producción. El único sandbox es el de nivel de inquilino: hasta que Certivant verifique su organización, las funciones de verificación en vivo están bloqueadas para todas las claves. Use una organización distinta si necesita datos de prueba totalmente separados.

Higiene recomendada de entornos

• Una clave por entorno. Cree claves separadas para local, staging y production. Si compromete un entorno, los otros dos siguen seguros.
• Etiquete las claves de forma descriptiva. payments-service-prod-2026Q2 es mejor que key1. La etiqueta aparece en el registro de auditoría.
• Establezca una caducidad en las claves que solo necesite temporalmente: para migraciones, demostraciones o acceso de terceros. Certivant rechaza la clave automáticamente cuando pasa expiresAt.
• Rote las claves una vez al año. Cree una clave nueva, cambie su servicio a ella y revoque la antigua cuando la nueva haya gestionado tráfico sin errores.
• Nunca incluya claves en git. Use su gestor de secretos (AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical) o, como mínimo, archivos .env incluidos en .gitignore.

Rotación sin tiempo de inactividad

Use Rotar en la clave (Desarrollador → Claves de API), o la API:

POST /api/kyc/api-keys/{id}/rotate        (dashboard session, api.access permission)
{ "overlapHours": 24 }

sequenceDiagram
  participant You
  participant Dashboard
  participant Service
  participant Certivant
  You->>Dashboard: Rotate key (overlap 24 h)
  Dashboard-->>You: ck_live_new_… (same scopes, restrictions, IP allowlist)
  You->>Service: Deploy with new key in env var
  Service->>Certivant: Authenticated requests with new key
  Note over Certivant: Old key still works until the overlap ends
  Certivant-->>Service: Old key → 401 api_key_rotated after the overlap

1. Rote la clave. La clave de reemplazo copia la etiqueta, los ámbitos, las restricciones, la lista de IP permitidas y la caducidad; su valor completo se muestra una sola vez.
2. Despliegue su servicio con la nueva clave durante el solapamiento (de 0 a 168 horas; por defecto, 24). La clave antigua sigue funcionando hasta entonces, y su marca de tiempo Último uso en el panel muestra si algo sigue llamándola.
3. Cuando termina el solapamiento, la clave antigua devuelve 401 api_key_rotated. Use overlapHours: 0 para revocarla de inmediato. También puede revocarla antes manualmente.

Qué ocurre cuando se revoca una clave

La siguiente solicitud que use la clave revocada devuelve 401. No hay periodo de gracia. Si revoca por error una clave que aún necesita, cree una nueva: no se puede deshacer una revocación.

Endpoints públicos (no se necesita clave)

Un pequeño conjunto de endpoints es público a propósito y no necesita una clave de API:

• GET /api/health y GET /api/status: sondas operativas.
• GET /api/branding: configuración de marca pública para la interfaz alojada.
• GET /api/kyc/public/status?ref=…: consulta de estado del solicitante por referencia externa.
• GET /api/kyc/public/forms/:slug y los endpoints de envío de formularios: usados por la interfaz de formularios alojada.

Se documentan por completitud, pero la mayoría de las integraciones nunca los llama directamente: la URL de sesión alojada gestiona toda la interacción pública.

Registro de auditoría

Cada llamada autenticada a la API queda registrada en KycAuditLog con el prefijo de la clave que llama, el endpoint y el tipo de actor (api). Puede revisar el historial en KYC → Registro de auditoría en el panel. Las entradas de auditoría se conservan durante toda la vida de la solicitud a la que se refieren.