Cuenta y llaves

Base: https://api.facturia.cl/v1. Todos los endpoints de este capítulo se autentican con Authorization: Bearer salvo que se diga lo contrario, y el sobre de error es el de Errores.

GET /account

Devuelve la cuenta y la llave en uso

La cuenta autenticada y la credencial en uso — email, plan, empresas_ready/total, y los scopes, el modo y la lista de empresas de la llave que llama.

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

Respuestas

GET /api_keys

Lista las llaves de API (solo metadatos; los secretos nunca se devuelven)

Una llave root ve todas las llaves de la cuenta. Una llave común se ve solo a sí misma.

curl -sS https://api.facturia.cl/v1/api_keys \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

POST /api_keys

Mintea una llave de API (solo con llave root)

Requiere una llave root (sk_live_root_… / sk_test_root_…) con el scope keys:write. Las barreras se aplican en el servidor: las empresas de la llave nueva deben ser un subconjunto de la lista de la llave que la mintea y sus scopes un subconjunto de los suyos (si no, 403 privilege_escalation); el modo se hereda; y una llave root no puede mintear otra llave root. El secret se devuelve una sola vez.

curl -sS -X POST https://api.facturia.cl/v1/api_keys \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"cliente — Comercial Andina","scopes":["documents:read","documents:write"]}'

Parámetros

Cuerpo

DELETE /api_keys/{key_id}

Revoca una llave de API de inmediato (solo con llave root)

Revoca una llave de inmediato y sin vuelta atrás. Requiere una llave root o una sesión de cuenta (403 root_key_required) — una llave normal no puede revocar llaves, ni siquiera a sí misma.

curl -sS -X DELETE https://api.facturia.cl/v1/api_keys/key_01K2QWB7T4N9 \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas

POST /api_keys/{key_id}/roll

Emite un secreto de reemplazo para una llave (solo con llave root)

El secreto anterior sigue funcionando 24 horas, así que puedes desplegar sin ventana de caída.

La rotación es un compare-and-swap sobre el hash actual de la llave, así que dos rotaciones de la misma llave nunca pueden aterrizar las dos: gana exactamente una y la perdedora responde 409 api_key_roll_conflict, cuyo secreto es el que está vivo. Rota una vez por llave.

curl -sS -X POST https://api.facturia.cl/v1/api_keys/key_01K2QWB7T4N9/roll \
  -H "Authorization: Bearer $FACTURIA_KEY"

Parámetros

Respuestas