API keys (autoservei)

Més enllà del dashboard de desenvolupador, Factuarea exposa tot el cicle de vida de les teves API keys des de l'API pública v1, perquè aprovisionis i rotis credencials de manera programàtica. Cinc endpoints sota /v1/account/api-keys cobreixen llistar, crear, recuperar, rotar el secret i revocar — tots limitats a l'empresa autenticada.

{api_key} és l'id de la key — un UUID v7 opac, no el seu prefix ni el seu secret. Mira els esquemes complets a la Referència de l'API.

Llista les teves keys

GET /v1/account/api-keys retorna les teves keys amb paginació per cursor. Cada key exposa el seu prefix, scopes, tier, environment i els timestamps del seu cicle de vida — mai el secret.

curl https://api.factuarea.com/v1/account/api-keys \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

{
  "data": [
    {
      "object": "api_key",
      "id": "0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f",
      "name": "Production sync",
      "prefix": "fact_live_8KqW3pXn",
      "scopes": ["invoices:read", "invoices:write"],
      "tier": "scale",
      "environment": "live",
      "active": true,
      "revoked": false,
      "last_used_at": "2026-06-23T18:04:11Z",
      "expires_at": null,
      "revoked_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

prefix són els primers caràcters de la key — segur de registrar en logs, no autentica. Fes-lo servir per reconèixer una key als teus propis panells sense desar mai el secret.

Crea una key

POST /v1/account/api-keys emet una nova key i retorna el seu secret en text pla exactament un cop. Desa'l en el moment que el reps — no hi ha cap endpoint per tornar-lo a llegir més tard.

curl -X POST https://api.factuarea.com/v1/account/api-keys \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Reporting export",
    "scopes": ["invoices:read", "pdfs:read"],
    "environment": "test"
  }'

Resposta (201):

{
  "data": {
    "object": "api_key",
    "id": "0190f2c0-77aa-7b21-8c33-1d2e3f405162",
    "name": "Reporting export",
    "prefix": "fact_test_1N0Fnyhh",
    "secret": "fact_test_1N0FnyhhR2VbY7TcA9eFmN5z",
    "scopes": ["invoices:read", "pdfs:read"],
    "tier": "scale",
    "environment": "test"
  }
}

Cos de la petició

El tier es deriva del pla de la teva empresa (o d'un boost de capacitat actiu quan és superior) — no es fixa des del cos. Si envies un tier, s'ignora. Demanar un scope fora del catàleg tancat, o un scope per sobre del teu pla, retorna 422 amb errors per camp.

El camp environment

Cada key pertany a un dels dos environments, fixat en crear-la i visible a l'objecte de la key:

Passa environment: test en crear una key per emetre una credencial de sandbox; omet-lo per a una key de producció. El prefix reflecteix l'environment, així que els distingeixes sense descodificar la key. Mira Mode de prova i sandbox per saber què es desactiva en test.

Rota el secret

POST /v1/account/api-keys/{api_key}/rotate_secret genera un nou prefix + secret i retorna el nou secret en text pla exactament un cop. El secret anterior continua funcionant durant una finestra de gràcia de 24 hores perquè puguis desplegar el nou sense downtime.

curl -X POST \
  https://api.factuarea.com/v1/account/api-keys/0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f/rotate_secret \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

{
  "data": {
    "object": "api_key",
    "id": "0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f",
    "prefix": "fact_live_Zq7mP4xV",
    "secret": "fact_live_Zq7mP4xVnR2VbY7TcA9eFmN5z",
    "scopes": ["invoices:read", "invoices:write"],
    "environment": "live"
  }
}

Revoca una key

POST /v1/account/api-keys/{api_key}/revoke invalida una key de manera permanent. Les peticions posteriors autenticades amb ella fallen amb 401. Un reason opcional (màx 500 caràcters) queda a l'audit log.

curl -X POST \
  https://api.factuarea.com/v1/account/api-keys/0190f2b1-1c4e-7a3d-9f10-0a1b2c3d4e5f/revoke \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Rotated out of the deploy pipeline"}'

Després de la revocació, les peticions amb aquesta key retornen 401 amb el codi genèric invalid_api_key — no un codi específic de «revocada»:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key proporcionada no es válida.",
    "request_id": "req_01JBVH7K9Y4N3CDQ2EHJB1AGSV"
  }
}

Això és anti-enumeració deliberada: l'API no revela mai si una key va ser revocada, ha caducat o no ha existit mai — tota key inutilitzable es veu igual per a un atacant. Ramifica la teva pròpia lògica segons el resultat 200/401, no segons un codi específic de revocada.

Scopes i aïllament

Els cinc endpoints estan protegits pels scopes d'account:

• account:read — llistar i recuperar keys.
• account:write — crear, rotar i revocar keys.

Totes les operacions estan limitades a l'empresa autenticada. Un id de key que pertany a una altra empresa retorna 404 api_key_not_found (de nou, anti-enumeració — no revela mai que la key existeix), mai 403.