API keys d'empreses filles

Emet, rota i revoca API keys acotades a una sola empresa filla, derivant els seus scopes de la key que crida — els endpoints api_keys sota una empresa gestionada.

Cada empresa gestionada té el seu propi joc d'API keys. Una key filla autentica peticions en nom d'aquesta única empresa — mai arriba a les empreses germanes ni al tenant mestre. És l'alternativa a manejar una filla amb el header X-Active-Profile: una key filla queda lligada a una empresa per sempre, en comptes de canviar-se per petició.

Cinc endpoints sota /v1/companies/{id}/api-keys cobreixen el seu cicle de vida.

Operació	Endpoint	Scope
Llistar keys filles	`GET /v1/companies/{id}/api-keys`	`api_keys:read`
Crear una key filla	`POST /v1/companies/{id}/api-keys`	`api_keys:write`
Recuperar una key filla	`GET /v1/companies/{id}/api-keys/{key}`	`api_keys:read`
Rotar el secret	`POST /v1/companies/{id}/api-keys/{key}/rotate-secret`	`api_keys:write`
Revocar una key filla	`DELETE /v1/companies/{id}/api-keys/{key}`	`api_keys:write`

Això replica l'autoservei d'API keys a nivell de compte, però acotat a una empresa filla en comptes del teu propi compte. Tant {id} (l'empresa) com {key} (l'API key) són valors UUID v7 opacs.

Crea una key filla

POST /v1/companies/{id}/api-keys emet una key per a l'empresa i retorna el seu secret en text pla exactament un cop. Requereix el scope api_keys:write.

curl -X POST \
  https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c/api-keys \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Producción Talleres García",
    "scopes": ["invoices:read", "invoices:write"]
  }'

Resposta (201):

{
  "data": {
    "object": "api_key",
    "id": "0190f2c0-77aa-7b21-8c33-1d2e3f405162",
    "name": "Producción Talleres García",
    "prefix": "fact_live_1OSf9KdP",
    "secret": "fact_live_1OSf9KdPR2VbY7TcA9eFmN5z",
    "scopes": ["invoices:read", "invoices:write"],
    "tier": "scale",
    "environment": "live"
  }
}

El secret es mostra només en aquesta resposta 201 i després d'una rotació. Cap endpoint el retorna després. Persisteix-lo en un gestor de secrets tan bon punt el reps — mai en un log ni en un repositori. Si el perds, rota la key.

Els scopes han de ser un subconjunt de la key pare

Els scopes que demanes per a una key filla han de ser un subconjunt dels de la key que fa la crida. Demanar un scope que la key que crida no té retorna 422 amb errors per camp — sense retallada silenciosa: la key no es crea amb una llista de scopes escurçada, falla la petició sencera.

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "No puedes conceder un scope que tu propia key no tiene.",
    "param": "scopes"
  }
}

Així, una key amb invoices:read invoices:write pot emetre keys filles amb qualsevol subconjunt d'aquests dos scopes, però mai amb clients:write. Aprovisiona primer una key mestra amb scopes suficients i deriva'n keys filles més estretes. L'environment i el tier mai es prenen del cos — s'hereten de la key que crida.

Camp	Obligatori	Notes
`name`	sí	Etiqueta llegible (1–120 caràcters).
`scopes`	sí	Un o més scopes, cadascun subconjunt dels de la key que crida.
`expires_at`	no	Instant futur ISO 8601 a partir del qual la key deixa d'autenticar.
`ip_allowlist`	no	Llista opcional d'IPs / CIDR permeses (IPv4, IPv6, `/N`).

Rota el secret

POST /v1/companies/{id}/api-keys/{key}/rotate-secret invalida de seguida el secret actual, genera un nou prefix + secret, i retorna el nou secret en text pla exactament un cop. Requereix el scope api_keys:write.

curl -X POST \
  https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c/api-keys/0190f2c0-77aa-7b21-8c33-1d2e3f405162/rotate-secret \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

La rotació té efecte a l'instant: qualsevol petició que segueixi fent servir el secret anterior deixa d'autenticar tan bon punt rotes. Desplega el nou secret abans de — o de manera atòmica amb — la rotació per evitar downtime. És irreversible.

Revoca una key filla

DELETE /v1/companies/{id}/api-keys/{key} revoca una key filla de manera permanent. Les peticions posteriors autenticades amb ella deixen de funcionar. Requereix el scope api_keys:write.

curl -X DELETE \
  https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c/api-keys/0190f2c0-77aa-7b21-8c33-1d2e3f405162 \
  -H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z"

La revocació és irreversible. Un cop revocada, la key no es pot restaurar — emet-ne una de nova si l'empresa encara necessita accés a l'API.

Scopes i aïllament

Les keys filles es protegeixen amb els scopes d'api_keys:

api_keys:read — llistar i recuperar keys filles.
api_keys:write — crear, rotar i revocar keys filles.

Tota operació està acotada al teu tenant mestre. Un id d'empresa que pertany a un altre mestre retorna 404 — mai 403, ni un endpoint de key filla d'una empresa que no gestiones. És el mateix aïllament entre mestres que regeix les empreses en si: un mestre només veu i actua sobre les seves pròpies empreses i les seves keys.