Claus acotades a una part del teu compte

Una API key pertany al compte, mai a un dels seus NIF, i el que decideix a quins NIF pot arribar és el seu àmbit: els scoped_company_ids que declares en emetre-la. Una clau acotada a un sol NIF autentica peticions que arriben a aquest: el segment {company} de la ruta no en pot anomenar cap altre, i la resta del compte li queda inabastable. L'àmbit pot contenir els teus propis NIF i també els que assoleixes per un accés cedit o per un compte gestionat.

És l'alternativa a gestionar tot el compte amb una sola credencial i anomenar el NIF a cada petició: una clau acotada queda fixada als seus NIF en emetre's, en lloc de canviar a cada petició. A més, cada NIF de l'àmbit té un nivell, view o operate, que mai no pot superar el de la persona que va emetre la clau.

Sis endpoints sota /v1/accounts/{account}/api-keys cobreixen el cicle de vida.

És el mateix autoservei que descriu API keys: aquesta pàgina tracta de l'àmbit de NIF que dones a una clau. Tant {account} com {api_key} són valors UUID v7 opacs, i llegeixes account.id de GET /v1/me. El subjecte és sempre el compte, i qui veu i gestiona una clau explica què en veu una clau.

Emet una clau acotada

POST /v1/accounts/{account}/api-keys emet una clau i retorna el seu secret en clar una sola vegada. Declara scoped_company_ids amb els NIF sobre els quals podrà operar la clau. Si l'omets, la clau arriba als mateixos NIF que la clau que l'emet, i mai a més. Requereix el scope account:write.

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

Resposta (201), amb una capçalera Location que porta la URL de la clau nova:

{
  "data": {
    "object": "api_key",
    "id": "0190f2c0-77aa-7b21-8c33-1d2e3f405162",
    "name": "Producción Talleres García",
    "prefix": "fact_live_1OSf9KdP",
    "scopes": ["invoices:read", "invoices:write"],
    "tier": "scale",
    "environment": "live",
    "created_at": "2026-01-15T09:30:00Z",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null,
    "is_active": true,
    "is_revoked": false,
    "secret": "fact_live_1OSf9KdPR2VbY7TcA9eFmN5z"
  }
}

El teu tram limita les claus actives. Emetre'n una per sobre del topall del teu tram respon 422 max_api_keys_exceeded, i quan el compte té més d'un NIF, tot el compte té a més un topall propi que respon 422 portfolio_max_api_keys_exceeded. El segon topall és pla dins d'un tram: donar d'alta més NIF mai no el puja.

L'àmbit mai no pot superar el de la clau emissora

Els NIF que demanes han d'estar dins de l'àmbit de la clau que fa la crida. Demanar-ne un al qual no arriba respon 422 business_rule_violation amb el subcodi nif_scope_exceeds_issuer. No hi ha retall silenciós: la clau no es crea arribant als NIF que sí hi caben, falla la petició sencera, i l'error llista només els identificadors que vas enviar i als quals la clau no arriba.

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "nif_scope_exceeds_issuer",
    "message": "La credencial nueva no puede alcanzar más NIFs que la credencial que la emite. Fuera del ámbito de la emisora: 01931b3e-8d5b-7a1f-9c2d-5e6f7a8b9c0d.",
    "param": "scoped_company_ids"
  }
}

Un NIF que no es resol, o que pertany a un altre compte, respon 422 invalid_param_value al mateix camp scoped_company_ids, i també un d'un compte que no et va donar accés: els casos són indistingibles a propòsit, perquè el camp no serveixi per sondejar quins NIF existeixen. Un NIF d'un accés cedit o d'un compte gestionat s'admet només mentre la relació sigui vigent i la teva clau ja hi arribi.

El nivell de cada NIF

Cada NIF de l'àmbit porta un nivell, view o operate, que és el topall del que la clau pot fer-hi. Es fixa quan el NIF entra a la clau, i és el menor de:

• el nivell en aquest NIF de la persona que emet la clau: un titular o administrador del compte té operate a tots els NIF d'aquest, i un member té el nivell del seu grant;
• per a un NIF al qual s'arriba per una relació entre comptes, el nivell de la relació, i el grant intern de la persona quan és member del compte receptor.

El que se'n deriva:

• Una clau que escriu només inclou NIF amb operate. Qualsevol scope que no sigui de lectura (:read), el scope * inclòs, necessita operate a cada NIF que la clau anomena, i una clau amb només scopes :read admet view o operate. Anomenar un NIF en el qual només tens view juntament amb un d'aquests scopes respon 422 business_rule_violation amb el subcodi nif_access_level_exceeds_emitter i no crea res. Si no declares scoped_company_ids, es deixen fora els NIF per sota del nivell que demanen els scopes, i quan no en queda cap la resposta és el mateix 422.
• Els NIF d'una relació queden sota el seu topall. Un NIF cedit o d'un compte gestionat entra com a màxim amb el nivell de la relació. Entra només si la persona que emet la clau pertany al teu compte, i un membre sense grant en ell no hi arriba. L'accés cedit ho explica des del costat receptor.
• El nivell es comprova a cada petició. El nivell que compta és el menor entre el desat a la clau i el que té avui la persona que la va emetre, així que una clau mai no escriu on la seva emissora ja no opera.

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "nif_access_level_exceeds_emitter",
    "message": "No puedes dar a la credencial más acceso del que tienes. Sin acceso suficiente en: 01931b3e-8d5b-7a1f-9c2d-5e6f7a8b9c0d. Una credencial con permisos de escritura solo alcanza NIF en los que operas.",
    "param": "scoped_company_ids"
  }
}

Quan la persona que va emetre una clau perd accés

El nivell desat d'una clau només baixa. Es recalcula a la baixa quan la persona que va emetre la clau perd nivell: es baixa o es revoca el seu grant, el seu rol passa d'admin a member, se la treu del compte, un NIF surt del compte o es traspassa, o l'accés que arriba a un NIF es redueix o acaba. Cadascuna d'aquestes coses té efecte a la petició següent:

• Un NIF que es queda sense nivell surt de l'àmbit de la clau.
• Un nivell baixat a view converteix les escriptures d'aquesta clau en aquest NIF en 403 company_read_only.
• Una clau que es queda amb l'àmbit buit es revoca.

Res no puja per si sol. Pujar un grant o un rol, o ampliar un accés, no toca les claus que ja existeixen: emet una clau nova, o canvia els NIF de l'existent, per obtenir el nivell nou.

Els scopes es concedeixen per intersecció dels plans

Un scope demanat es concedeix només si tots els NIF de l'àmbit l'habiliten pel seu pla. Els teus propis NIF comparteixen el pla del teu compte, i un NIF al qual s'arriba per una relació aporta el pla del seu propi compte, així que barrejar-los pot respondre 422 scope_not_allowed_by_plan. L'excés mai no es retalla en silenci. 422 scope_not_allowed_in_sandbox cobreix un scope que una clau de proves no pot portar. La llista de scopes queda fixada en emetre: ampliar-la vol dir emetre una altra clau. L'environment i el tier mai no es prenen del cos, i el tier es deriva del pla del compte.

Claus de proves

Una clau amb environment: test arriba només a l'empresa sandbox del teu compte, així que declarar scoped_company_ids amb ella respon 422 invalid_param_value en aquest camp: emet-la sense scoped_company_ids. Una credencial fact_test_ no pot emetre claus, canviar-ne l'àmbit, rotar-les ni revocar-les: aquestes quatre operacions responen 403 live_credential_required sense escriure res, així que una clau de proves mai no emet una clau de producció. Per obtenir una clau de proves, emet-la amb una clau de producció i environment: test, o crea-la a l'aplicació web. Provar comptes gestionats cobreix la resta del que pot fer una clau de proves.

{
  "error": {
    "type": "authorization_error",
    "code": "live_credential_required",
    "message": "Esta operación modifica la cuenta y exige una clave de producción (fact_live_)",
    "doc_url": "https://docs.factuarea.com/guides/errors#live_credential_required",
    "request_id": "req_01J8Y3M2Q40000000000000009"
  }
}

Canvia els NIF d'una clau

PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope substitueix els NIF d'una clau que ja està desplegada, i no en canvia el secret. scoped_company_ids és la llista resultant completa, no un delta, amb almenys un NIF. Fes-lo servir per afegir els NIF dels teus clients a una clau que ja vas emetre, o per acotar-la. Requereix el scope account:write.

curl -X PATCH \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/api-keys/$API_KEY_ID/nif-scope \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scoped_company_ids": [
      "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
      "01931b3e-8d5b-7a1f-9c2d-5e6f7a8b9c0d"
    ]
  }'

Resposta (200), l'àmbit amb el qual queda la clau:

{
  "data": {
    "id": "0190f2c0-77aa-7b21-8c33-1d2e3f405162",
    "object": "api_key_nif_scope",
    "scope": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
        "tax_id": "B12345674",
        "name": "Talleres García SL"
      },
      {
        "id": "01931b3e-8d5b-7a1f-9c2d-5e6f7a8b9c0d",
        "tax_id": "B87654323",
        "name": "Distribuciones Norte SL"
      }
    ]
  }
}

S'apliquen els mateixos topalls que en emetre una clau:

• El teu propi abast. Només pots canviar una clau l'àmbit actual de la qual és dins del teu, i l'àmbit nou mai no pot superar el teu: nif_scope_exceeds_issuer en cas contrari. Cada NIF ha de ser al teu compte o assolir-se per una relació vigent, i a l'entorn de la clau.
• Nivells. Un NIF que entra pren el nivell que té ara la persona que va emetre la clau, i es rebutja amb nif_access_level_exceeds_emitter si aquesta persona no hi arriba amb el nivell que necessita la clau. Els NIF que continuen conserven el seu nivell desat: canviar l'àmbit mai no en puja cap.
• Plans. Cada scope que la clau ja té es comprova de nou contra el pla de tots els NIF de l'àmbit nou. Un scope que un d'ells no permet respon 422 scope_not_allowed_by_plan i no canvia res.
• El que no es pot canviar. Una clau publicada en un navegador, perquè té orígens permesos, manté el seu àmbit congelat i respon 422 resource_immutable. Una clau revocada respon 422 api_key_already_revoked, i una clau de proves no pot canviar el seu àmbit. Enviar de nou el mateix àmbit no canvia res.

Qui veu i gestiona una clau

Una clau llista, consulta, rota, revoca i canvia l'àmbit d'una altra clau del seu compte només si tot l'àmbit d'aquella altra és dins del seu. Qualsevol altra cosa respon 404 api_key_not_found, igual que una clau que no existeix o que pertany a un altre compte. És contenció i no intersecció perquè gestionar una clau dona el seu secret, i el secret dona tot el seu àmbit: una clau acotada a {A} podria, altrament, rotar una acotada a {A, B} i arribar a B.

Així, una clau acotada a un NIF no pot veure les claus de les seves germanes, i una clau veu tota clau els NIF de la qual ella també assoleix. El llistat inclou les claus revocades, perquè en conservis l'historial, i mai no retorna un secret. La contenció compta els NIF que una clau assoleix avui: els que va deixar enrere un accés que va acabar no compten.

Rota el secret

POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret genera un prefix i un secret nous i retorna el secret nou en clar una sola vegada. El secret anterior continua funcionant durant una finestra de gràcia de 24 hores, perquè puguis desplegar el nou sense talls. Exigeix una Idempotency-Key i el scope account:write.

curl -X POST \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/api-keys/$API_KEY_ID/rotate-secret \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Revoca una clau

POST /v1/accounts/{account}/api-keys/{api_key}/revoke revoca una clau de manera permanent. Les peticions posteriors autenticades amb ella fallen amb 401. Un reason opcional, de fins a 500 caràcters, queda al registre d'auditoria. Exigeix una Idempotency-Key i el scope account:write. Pots revocar la clau que estàs fent servir, i en fer-ho et talles el teu propi accés.

curl -X POST \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/api-keys/$API_KEY_ID/revoke \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "reason": "Rotated out of the deploy pipeline" }'

Scopes i aïllament

La gestió de claus es controla amb els scopes de compte:

• account:read llista i consulta les claus del teu compte que veus.
• account:write les emet, en canvia l'àmbit, les rota i les revoca.

Tota operació està limitada al teu compte. Un {account} que no és teu respon 404 account_not_found, mai un 403, i és indistingible d'un compte que no existeix. El mateix aïllament regeix la cartera de NIF i anomenar un NIF a la ruta: una clau només pot veure i actuar sobre els NIF del seu àmbit.

Permisos de botigues

La gestió de botigues fa servir stores:read i stores:write ; els scopes del proveïdor són woocommerce_store:read , woocommerce_store:write , shopify_store:read i shopify_store:write . Les proves de connexió requereixen el scope d’escriptura del proveïdor. Aquests scopes s’assignen a API keys i queden fora del consentiment OAuth. Consulta la taula d’operacions de botigues.

Relacionat