Autenticación

API keys de Simplo (sk_simplo_), el header X-Api-Key, creación, revocación e higiene de credenciales.

API keys (recomendado)

Simplo autentica con API keys por empresa. Una key se ve como sk_simplo_... y se muestra una sola vez al crearla — guárdala en un gestor de secretos (Simplo solo conserva su hash SHA-256 y un prefijo de 8 caracteres para mostrar).

La key viaja en el header X-Api-Key. Con el SDK:

import Simplo from '@simplohq/sdk';

const simplo = new Simplo({ apiKey: process.env.SIMPLO_API_KEY });

Si omites apiKey, el cliente lee la variable de entorno SIMPLO_API_KEY y lanza un error de inmediato (no en la primera request) si no existe ninguna.

La credencial es la empresa. Una API key está ligada a exactamente una empresa: cada llamada queda acotada a ella y ningún parámetro puede ampliar ese alcance. Para operar varias empresas, ver Multi-empresa.

Crear, listar y revocar keys

Puedes gestionar tus keys desde Configuración → API keys en tu cuenta de Simplo (solo dueño o administrador de la empresa), o por API autenticándote con tu JWT de sesión:

curl -sS -X POST https://api.simplo.cl/api/v1/api-keys \
  -H "Authorization: Bearer $SIMPLO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Backend de facturación"}'

La respuesta 201 Created incluye el campo key esta única vez — no se puede recuperar después:

{
  "id": "a1b2c3d4-...",
  "name": "Backend de facturación",
  "prefix": "sk_simpl",
  "revoked": false,
  "created_at": "2026-06-13T12:00:00Z",
  "key": "sk_simplo_3f9a...e1"
}

Para listar o revocar:

curl -sS https://api.simplo.cl/api/v1/api-keys \
  -H "Authorization: Bearer $SIMPLO_JWT"

curl -sS -X DELETE https://api.simplo.cl/api/v1/api-keys/$KEY_ID \
  -H "Authorization: Bearer $SIMPLO_JWT"

El listado nunca devuelve el valor completo de la key, solo su metadata (prefix, scopes, last_used_at, revoked). Revocar es idempotente y tiene efecto inmediato.

Higiene de keys

Nunca envíes una API key a un navegador o app móvil. Llama a Simplo desde tu backend.
Nunca la commitees. Usa variables de entorno o un gestor de secretos.
Rota creando una key nueva, desplegándola y revocando la antigua. La revocación es inmediata.

Bearer tokens (avanzado)

Si ya tienes un JWT emitido por Simplo (por ejemplo dentro de una integración que autentica usuarios contra Simplo), puedes pasarlo en lugar de una API key. Se envía como Authorization: Bearer <token>:

const simplo = new Simplo({ token: sessionJwt });

Prefiere API keys para integraciones server-to-server: no expiran con el calendario de una sesión y son revocables individualmente.

Modos de falla

Status	Clase de error	Significado
401	`AuthenticationError`	Credencial ausente, malformada, revocada, expirada o desconocida.
403	`PermissionError`	Credencial válida, pero sin permiso para esta acción.

La API intencionalmente no distingue por qué ocurrió un 401 (anti-enumeración). Revisa el nombre del header (X-Api-Key), el prefijo de la key (sk_simplo_) y que no esté revocada.

Ver Errores para el manejo completo.