KilaSifen Docs

Autenticación y scopes

Protegé la credencial y otorgá únicamente las capacidades necesarias.

Cada request protegido usa una credencial privada en el header X-API-Key.

X-API-Key: ks_••••••••••••••••

Las claves de consumidor empiezan con ks_. No hay claves «live» y «test»: el ambiente de SIFEN lo fija la instancia de KilaSifen, no la clave.

Dónde guardar la clave

Guardala en el secret manager o variables cifradas del backend consumidor. No debe aparecer en Git, logs, analytics, localStorage ni código enviado al navegador.

Obtener y verificar una clave

Un consumidor no crea sus propias claves: las emite un administrador de la plataforma con POST /v1/admin/consumers/{consumer_id}/credentials, con 1 a 5 scopes de consumidor. La respuesta muestra el secreto completo (api_key) una sola vez; después sólo queda visible key_prefix.

curl https://TU_API/v1/auth/check \
  -H "X-API-Key: $KILA_API_KEY"

/v1/auth/check responde 200 con data.authenticated: true si la clave es válida, y 401 si falta (auth.missing_api_key) o no es válida (auth.invalid_api_key). No informa los scopes.

Scopes

ScopePermite
tenant:readLeer y listar emisores (GET /v1/emitters) y su /health, documentos, XML, KuDE, jobs, timbrados, webhooks y entregas, y consultar SIFEN (estado de un documento por CDC y RUC).
tenant:writeActualizar el emisor (razón social, perfil fiscal), desactivarlo (no hay ruta para reactivarlo) y administrar webhooks: registrar, actualizar, probar y reenviar entregas. Cambiar el CSC requiere además secrets:write.
fiscal:writeCrear facturas, notas de crédito y notas de débito; cancelar, inutilizar, nominar una factura innominada y leer esos eventos; crear y activar timbrados; reconciliar un documento y reintentar un job del emisor.
secrets:writeCargar, listar y activar certificados PKCS#12; junto con tenant:write, cambiar el CSC de un emisor que ya existe.
emitters:createDar de alta emisores, con su CSC si lo enviás en el alta, que quedan siempre a nombre del consumidor de la clave (ver Emisores). Otorgalo sólo a integradores de confianza: RUC y external_id son únicos en toda la plataforma.
platform:adminSuperusuario: pasa por alto los scopes y la pertenencia de emisores. Administra consumidores y credenciales, crea emisores para cualquier consumidor, lista los de todos y usa las rutas raw, /v1/jobs, /v1/webhook-deliveries y la consola /admin. La API nunca lo emite (422 credentials.invalid_scopes): sólo existe como clave de arranque en KILA_SIFEN_API_KEYS. Nunca se entrega a un ERP.

Una clave sin el scope necesario recibe 403 auth.insufficient_scope. Un recurso perteneciente a otro consumidor responde 404, no 403, para no revelar su existencia.

Clave de un ERP

Un ERP que da de alta a sus clientes y emite por ellos necesita los cinco scopes de consumidor: emitters:create, tenant:read, tenant:write, fiscal:write y secrets:write. Si tu ERP sólo emite para emisores que ya dio de alta un administrador, alcanza con tenant:read y fiscal:write, más secrets:write si también carga los certificados.

Rotación

  1. Pedí al administrador una segunda credencial para tu consumidor (POST /v1/admin/consumers/{consumer_id}/credentials) y guardá el api_key en ese momento: no se vuelve a mostrar.
  2. Desplegala en tu backend y verificala con GET /v1/auth/check.
  3. Cuando todo el tráfico use la nueva clave, pedí revocar la anterior (POST /v1/admin/consumers/{consumer_id}/credentials/{credential_id}/revoke). Desde ese momento la clave revocada responde 401 auth.invalid_api_key.

En esta página