Account and keys
The authenticated account, the key in use, and minting keys with a root key.
Base: https://api.facturia.cl/v1. Every endpoint in this chapter authenticates with Authorization: Bearer unless stated otherwise, and the error envelope is the one in Errors.
| Method | Path | What it does |
|---|---|---|
GET | /account | Retrieve the account and the key in use |
GET | /api_keys | List API keys (metadata only; secrets are never returned) |
POST | /api_keys | Mint an API key (root key only) |
DELETE | /api_keys/{key_id} | Revoke an API key immediately (root key only) |
POST | /api_keys/{key_id}/roll | Issue a replacement secret for a key (root key only) |
GET /account
Retrieve the account and the key in use
The authenticated account and the credential in use — email, plan, empresas_ready/total, and the calling key's own scopes, mode and allowlist.
curl -sS https://api.facturia.cl/v1/account \
-H "Authorization: Bearer $FACTURIA_KEY"Responses
| Code | Meaning | Body |
|---|---|---|
200 | The account. | Account |
400 | empresa_header_forbidden — this operation is account-level; a Facturia-Empresa header on it is refused rather than silently ignored. | ErrorResponse |
401 | Missing, malformed or revoked key. | ErrorResponse |
429 | Too many requests. | ErrorResponse |
default | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on error.code, never on the HTTP status alone or on error.message — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |
GET /api_keys
List API keys (metadata only; secrets are never returned)
A root key sees every key on the account. An ordinary key sees only itself.
curl -sS https://api.facturia.cl/v1/api_keys \
-H "Authorization: Bearer $FACTURIA_KEY"Parameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
limit | query | — | integer | |
cursor | query | — | string | Opaque cursor from a previous response's next_cursor. |
Responses
| Code | Meaning | Body |
|---|---|---|
200 | A list of API keys. | lista de ApiKey |
401 | Missing, malformed or revoked key. | ErrorResponse |
429 | Too many requests. | ErrorResponse |
default | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on error.code, never on the HTTP status alone or on error.message — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |
POST /api_keys
Mint an API key (root key only)
Requires a root key (sk_live_root_… / sk_test_root_…) carrying keys:write.
Guardrails, enforced server-side: the new key's empresas must be a subset of the
minter's allowlist and its scopes a subset of the minter's scopes (violations return
403 privilege_escalation); mode is inherited from the minter; root keys cannot mint
root keys. The secret is returned exactly once.
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"]}'Parameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
Idempotency-Key | header | — | string | Client-generated key, unique per logical operation, retained 24h and scoped to (account, empresa, endpoint). Replays return the original response with Facturia-Idempotent-Replay: true. Same key + different body → 409. |
Body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
mode | live · test | — | |
scopes | documents:read · documents:write · received:read · received:write · empresas:read · empresas:write · folios:write · tax:read · tax:write · webhooks:read · webhooks:write · usage:read · keys:write · mandato:write · mandato:attest · onboarding:write · onboarding:attest[] | yes | |
empresas | Rut[] | — | Subset of the minting key's allowlist. A single RUT makes it an empresa token. |
| Responses |
| Code | Meaning | Body |
|---|---|---|
201 | The minted key, including its secret. | ApiKeyWithSecret |
400 | Malformed or missing input. | ErrorResponse |
401 | Missing, malformed or revoked key. | ErrorResponse |
403 | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse |
429 | Too many requests. | ErrorResponse |
default | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on error.code, never on the HTTP status alone or on error.message — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |
DELETE /api_keys/{key_id}
Revoke an API key immediately (root key only)
Revoke a key immediately and irreversibly. Requires a root key or an account session (403 root_key_required) — an ordinary key cannot revoke keys, itself included.
curl -sS -X DELETE https://api.facturia.cl/v1/api_keys/key_01K2QWB7T4N9 \
-H "Authorization: Bearer $FACTURIA_KEY"Parameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
key_id | path | yes | string |
Responses
| Code | Meaning | Body |
|---|---|---|
204 | Revoked. Revocation is immediate and unrecoverable. | — |
401 | Missing, malformed or revoked key. | ErrorResponse |
403 | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse |
404 | No such object under this key. | ErrorResponse |
429 | Too many requests. | ErrorResponse |
default | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on error.code, never on the HTTP status alone or on error.message — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |
POST /api_keys/{key_id}/roll
Issue a replacement secret for a key (root key only)
The previous secret keeps working for 24 hours so you can deploy without downtime.
The roll is a compare-and-swap on the key's current hash, so two rolls of the
same key can never both land: exactly one wins and the loser answers
409 api_key_roll_conflict, whose secret is the live one. Roll once per key.
curl -sS -X POST https://api.facturia.cl/v1/api_keys/key_01K2QWB7T4N9/roll \
-H "Authorization: Bearer $FACTURIA_KEY"Parameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
key_id | path | yes | string |
Responses
| Code | Meaning | Body |
|---|---|---|
200 | The key with its new secret. | ApiKeyWithSecret |
401 | Missing, malformed or revoked key. | ErrorResponse |
403 | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse |
409 | State conflict — idempotency reuse, duplicate external_id, artifact not ready. | ErrorResponse |
429 | Too many requests. | ErrorResponse |
default | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on error.code, never on the HTTP status alone or on error.message — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |