# Llaves de API (/docs/autenticacion)

La autenticación es un solo bearer token.

```bash
curl https://api.facturia.cl/v1/documents \
  -H "Authorization: Bearer sk_live_9lQpV3fA2mKcRt7wZxYb1Nde"
```

| Prefijo    | Modo                                      | ¿Habla con el SII?                                        | Costo                                                                          |
| ---------- | ----------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `sk_test_` | **test** — sandbox completamente simulado | Nunca                                                     | Gratis para siempre                                                            |
| `sk_live_` | **live** — emisión real                   | Sí (certificación o producción del SII, según la empresa) | El plan único: $19.990 CLP + IVA al mes **por empresa**, documentos ilimitados |

Las llaves tienen alcance de cuenta, se muestran una sola vez, se guardan hasheadas y se revocan
individualmente. Puedes crearlas en el panel o por API.

Una llave carga tres cosas:

* un **modo** (`test` / `live`) — inmutable, codificado en el prefijo;
* un **conjunto de scopes** — ver [Scopes](/docs/autenticacion/scopes);
* una **lista blanca de empresas** — `["*"]` (toda empresa de la cuenta, incluidas las que se creen
  después) o una lista explícita de RUT.

> **Trampa — No hay llave publicable en la v1**
>
> La API es servidor a servidor. Nunca pongas una llave secreta en un navegador, una app móvil ni el
> prompt de un agente que un tercero pueda leer. Si una llave se filtra, revócala: la revocación es
> inmediata e irrecuperable.
>
> Para darle un artefacto a alguien sin llave — el receptor, su contador, un hilo de WhatsApp — existen
> los [enlaces públicos](/docs/emision/artefactos#enlaces-publicos), que son firmados, inadivinables,
> con vencimiento y revocables, y no pueden escalarse a una credencial de API.

## Quién soy [#quién-soy]

```bash
curl https://api.facturia.cl/v1/account \
  -H "Authorization: Bearer $FACTURIA_KEY"
```

```json
{
  "object": "account",
  "id": "acct_01K2QW8V6ZR3T5NM",
  "name": "Connect Core",
  "key": {
    "id": "key_01K2QWA3F2",
    "name": "production-backend",
    "mode": "live",
    "last4": "1Nde",
    "scopes": ["documents:read", "documents:write", "tax:read"],
    "empresas": ["77928532-4", "78281439-7"],
    "created_at": "2026-08-01T17:22:04Z",
    "last_used_at": "2026-08-14T13:04:10Z"
  },
  "limits": { "requests_per_minute": 300, "emissions_per_second": 10 }
}
```

Es la llamada barata para un health check: te dice qué llave estás usando, con qué scopes, sobre qué
empresas y con qué límites.

## Token de empresa [#token-de-empresa]

Una llave cuya lista blanca tiene exactamente una empresa es un **token de empresa**: el header
`Facturia-Empresa` pasa a ser opcional, y si lo mandas debe coincidir o recibes
`400 empresa_mismatch`.

Es la forma recomendada cuando integras una sola compañía o cuando le entregas una llave al sistema
de tu cliente: la llave no puede direccionar nada más que ese RUT.

## Verificación de correo [#verificación-de-correo]

Registrarte no exige probar tu dirección, y tampoco lo exige iniciar sesión, leer nada, ni usar el
producto completo en **modo test**. La verificación bloquea exactamente una cosa: crear una
credencial **live**.

```bash
# Confirmar — el token viene del enlace del correo. No necesita sesión:
# quien hace clic tiene un enlace, posiblemente en otro dispositivo.
curl -sS https://api.facturia.cl/account/verify \
  -H "Content-Type: application/json" -d '{"token":"..."}'

# Reenviar — este sí necesita la sesión, para que no nos puedan usar para mandarle correo a nadie.
curl -sS -X POST https://api.facturia.cl/account/verification/resend \
  -H "Authorization: Bearer $TOKEN"
```

El enlace es de un solo uso, vive 24 horas y está ligado a la dirección a la que se envió: si el
correo de la cuenta cambia en el intertanto, el token se rechaza en vez de confirmar una dirección a
la que nunca se entregó. Hacer clic dos veces es un éxito, no un error. Los reenvíos tienen límite de
tasa y responden `429` con `Retry-After`.

Mintear una llave `sk_live_` desde una cuenta sin verificar devuelve
`403 email_verification_required`.

- [Scopes y empresas](/docs/autenticacion/scopes): Qué concede cada scope y cómo se combina con la lista blanca.

- [Llaves root y rotación](/docs/autenticacion/llaves-root): Mintear una llave por cliente sin que un humano abra un panel.

- [Límites de tasa](/docs/autenticacion/limites): Los buckets publicados y los headers que te dicen dónde estás.