Chei API și domenii de acces

Fiecare cerere către API-ul Sursa se face cu o cheie API a organizației. O cheie aparține organizației, nu unei persoane: funcționează în continuare când angajatul care a creat-o pleacă, iar ce poate face se stabilește pe cheia însăși.

Ce are voie să facă o cheie

Trei setări ale unei chei decid ce poate vedea și modifica o cerere făcută cu ea. Fiecare dintre ele doar le restrânge pe celelalte.

Setare	Ce controlează
Rol	`admin`, `editor`, `verifier` sau `viewer`, aceleași roluri pe care le au utilizatorii. Cheia poate face ce poate face un utilizator cu acel rol.
Domenii de acces	Ce părți ale API-ului poate apela cheia, de exemplu `cards:read` sau `webhooks:manage`. Vedeți Domeniile de acces ale cheilor.
Profil de date	Opțional. Limitează cheia la categoriile de cunoștințe permise de profil, ca pe un utilizator cu acel profil.

O cheie poate fi, de asemenea, limitată la anumite colecții și poate primi o dată de expirare. O cerere în afara acestor limite eșuează: un domeniu lipsă returnează 403 cu codul api_keys.scope, iar un obiect pe care cheia nu îl poate vedea returnează 404, exact ca și cum nu ar exista.

Dați fiecărei integrări propria cheie, cu cel mai restrâns rol și cele mai restrânse domenii de care are nevoie. Un job de sincronizare care doar scrie documente nu are nevoie de admin; un job de raportare nu are nevoie de domenii de scriere.

Crearea unei chei

Un administrator al organizației creează chei în Sursa, în Administration → API keys (administrare → chei API), sau cu POST /v1/api-keys, folosind o cheie sau o sesiune cu rolul 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"
  }'

Răspunsul conține valoarea cheii în key. Ea este afișată o singură dată: Sursa păstrează doar un hash al ei și nu o mai poate afișa. O cheie arată ca kb_ urmat de 43 de caractere; primele caractere (prefix) apar în lista cheilor, ca să puteți deosebi cheile între ele.

Fără scopes, cheia primește domeniile de acces ale rolului ei. Transmiteți scopes pentru a o restrânge și mai mult. Fără expires_at, cheia nu expiră.

Păstrați cheile secrete

Stocați cheile într-un manager de secrete sau în variabilele de mediu ale serviciului, niciodată în codul sursă.
Folosiți cheile doar de pe serverele dumneavoastră. Sursa acceptă cereri din browsere (CORS este deschis), dar o cheie dintr-o pagină web este vizibilă pentru oricine o deschide.
Nu trimiteți niciodată o cheie într-un URL. Trimiteți-o doar în antetul Authorization.
Dacă o cheie a fost divulgată, revocați-o imediat și creați una nouă.

Verificarea unei chei

GET /v1/me returnează cheia, rolul ei, domeniile efective, profilul de date, data de expirare și limita de frecvență. Funcționează cu orice cheie validă, oricare ar fi domeniile ei, așa că folosiți-l ca test de conexiune al integrării și când investigați un 403.

Reînnoirea unei chei

Reînnoirea înlocuiește o cheie fără să oprească integrarea. Cea mai rapidă cale este reînnoirea valorii cheii: POST /v1/api-keys/{key_id}/roll emite o valoare nouă pentru aceeași cheie, cu același rol, aceleași domenii de acces, aceleași colecții și aceeași dată de expirare. Valoarea anterioară rămâne valabilă timp de overlap_hours (implicit 24 de ore, cel mult 168), ca să puteți instala între timp valoarea nouă; POST /v1/api-keys/{key_id}/revoke-previous încheie suprapunerea mai devreme.

Pentru a înlocui cheia cu una diferită:

Creați o cheie nouă cu același rol, aceleași domenii de acces și același profil de date.
Instalați cheia nouă în integrare.
Urmăriți cheia veche în Administration → API keys (sau last_used în GET /v1/api-keys) până când nu mai este folosită.
Revocați cheia veche.

Setați o dată de expirare pentru chei și reînnoiți-le înainte de ea. Sursa îi avertizează pe administratorii organizației înainte ca o cheie să expire; o cheie expirată returnează 401 cu codul api_keys.expired.

Revocarea unei chei

Revocați o cheie în Administration → API keys sau cu DELETE /v1/api-keys/{key_id}. Revocarea intră în vigoare în câteva secunde pe fiecare server API. Cererile cu o cheie revocată returnează 401 cu codul auth.not_authenticated.

Cheile unei surse personalizate

O sursă personalizată are propriul tip de cheie. Aceasta începe cu kbsrc_, poate doar să scrie documente în acea singură sursă și nu poate citi sau căuta nimic. Este cea mai sigură cheie pe care o puteți da unei platforme de integrare precum Zapier. Creați-o pe pagina sursei, în API keys, sau cu POST /v1/sources/{source_id}/push-keys.

Când cheile nu sunt disponibile

Cheile API fac parte din planul organizației. Dacă planul nu le include, crearea unei chei și orice cerere cu o cheie returnează 403 cu codul api_keys.feature_disabled.