Claus d’API i àmbits

Cada sol·licitud a l’API de Sursa es fa amb una clau d’API de la vostra organització. Una clau pertany a l’organització, no a una persona: continua funcionant quan la persona que la va crear deixa l’empresa, i el que pot fer es defineix a la mateixa clau.

Què pot fer una clau

Tres paràmetres d’una clau decideixen què pot veure i canviar una sol·licitud feta amb ella. Cadascun només restringeix el que permeten els altres.

Paràmetre	Què controla
Role (rol)	`admin`, `editor`, `verifier` o `viewer`, els mateixos rols que tenen les persones. La clau pot fer el que pot fer un usuari amb aquest rol.
Scopes (àmbits)	Quines parts de l’API pot cridar la clau, per exemple `cards:read` o `webhooks:manage`. Vegeu Àmbits de les claus.
Data profile (perfil de dades)	Opcional. Limita la clau a les categories de coneixement que permet el perfil, igual que un usuari amb aquest perfil.

Una clau també es pot limitar a algunes col·leccions i se li pot posar una data de caducitat. Una sol·licitud fora d’aquests límits falla: si falta un àmbit, es retorna 403 amb el codi api_keys.scope, i un objecte que la clau no pot veure retorna 404, exactament com si no existís.

Doneu a cada integració la seva pròpia clau amb el rol i els àmbits mínims que necessiti. Un treball de sincronització que només escriu documents no necessita admin; un treball d’informes no necessita àmbits d’escriptura.

Crear una clau

Qui administra l’organització crea les claus a Sursa a Administration → API keys (administració, claus d’API), o amb POST /v1/api-keys mitjançant una clau o una sessió que tingui el rol admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

La resposta conté el valor de la clau a key. Es mostra una sola vegada: Sursa només en conserva un hash i no la pot tornar a mostrar. Una clau té la forma kb_ seguit de 43 caràcters; els primers caràcters (prefix) es mostren a la llista de claus perquè les pugueu distingir.

Sense scopes, la clau rep els àmbits del seu rol. Passeu scopes per restringir-la més. Sense expires_at, la clau no caduca.

Mantenir les claus en secret

Deseu les claus en un gestor de secrets o en variables d’entorn del vostre servei, mai al codi font.
Feu servir les claus només des dels vostres servidors. Sursa accepta sol·licituds des de navegadors (CORS és obert), però una clau en una pàgina web la pot veure tothom qui l’obre.
No envieu mai una clau en una URL. Envieu-la només a la capçalera Authorization.
Si una clau es filtra, revoqueu-la immediatament i creeu-ne una de nova.

Comprovar una clau

GET /v1/me retorna la clau, el seu rol, els àmbits efectius, el perfil de dades, la caducitat i el límit de freqüència. Funciona amb qualsevol clau vàlida, tingui els àmbits que tingui, de manera que el podeu fer servir com a prova de connexió de la vostra integració i quan investigueu un 403.

Fer rotar una clau

La rotació substitueix una clau sense aturar la integració. La manera més ràpida és fer rotar la clau: POST /v1/api-keys/{key_id}/roll emet un valor nou per a la mateixa clau, amb el mateix rol, els mateixos àmbits, les mateixes col·leccions i la mateixa caducitat. El valor anterior continua funcionant durant overlap_hours (24 hores per defecte, fins a 168), de manera que mentrestant podeu desplegar el valor nou; POST /v1/api-keys/{key_id}/revoke-previous acaba el solapament abans d’hora.

Per substituir una clau per una altra de diferent:

Creeu una clau nova amb el mateix rol, els mateixos àmbits i el mateix perfil de dades.
Desplegueu la clau nova a la vostra integració.
Vigileu la clau antiga a Administration → API keys (o last_used a GET /v1/api-keys) fins que ja no es faci servir.
Revoqueu la clau antiga.

Poseu una data de caducitat a les claus i feu-les rotar abans que arribi. Sursa avisa els administradors de l’organització abans que una clau caduqui; una clau caducada retorna 401 amb el codi api_keys.expired.

Revocar una clau

Revoqueu una clau a Administration → API keys o amb DELETE /v1/api-keys/{key_id}. La revocació té efecte en pocs segons a tots els servidors de l’API. Les sol·licituds amb una clau revocada retornen 401 amb el codi auth.not_authenticated.

Claus d’una font personalitzada

Una font personalitzada té el seu propi tipus de clau. Comença per kbsrc_, només pot escriure documents en aquella font i no pot llegir ni cercar res. És la clau més segura per donar a una plataforma d’integració com Zapier. Creeu-la a la pàgina de la font, a API keys (claus d’API de la font), o amb POST /v1/sources/{source_id}/push-keys.

Quan les claus no estan disponibles

Les claus d’API formen part del pla de l’organització. Si el pla no les inclou, la creació d’una clau i totes les sol·licituds amb clau retornen 403 amb el codi api_keys.feature_disabled.