# 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).

> **Beta privada:**
> La API de Simplo está en **beta privada**. Las API keys son la forma de
> autenticarse, y el acceso con key a la superficie de emisión (facturación) se
> habilita cuenta por cuenta durante el rollout — tener una key no garantiza por
> sí solo acceso de emisión hasta que tu cuenta esté habilitada. Hoy las keys
> llevan el scope de lectura `agent:read`. Pide acceso a la beta en
> [hola@simplo.cl](mailto:hola@simplo.cl).

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

```ts
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](/comienza/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:

```bash
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:

```json
{
  "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:

```bash
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>`:

```ts
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](/referencia/errores/) para el manejo completo.

---

Versión HTML: https://docs.simplo.cl/comienza/autenticacion/ · Índice para agentes: https://docs.simplo.cl/llms.txt