Kľúče API a rozsahy

Každá požiadavka na Sursa API sa posiela s kľúčom API vašej organizácie. Kľúč patrí organizácii, nie človeku: funguje ďalej aj vtedy, keď zamestnanec, ktorý ho vytvoril, odíde, a to, čo smie robiť, je nastavené priamo na kľúči.

Čo kľúč smie robiť

O tom, čo požiadavka s kľúčom smie vidieť a meniť, rozhodujú tri nastavenia kľúča. Každé z nich ostatné len zužuje.

Nastavenie	Čo určuje
Rola	`admin`, `editor`, `verifier` alebo `viewer`, tie isté roly, aké majú ľudia. Kľúč smie robiť to, čo používateľ s touto rolou.
Rozsahy	Ktoré časti API smie kľúč volať, napríklad `cards:read` alebo `webhooks:manage`. Pozri Rozsahy kľúča.
Dátový profil	Nepovinný. Obmedzí kľúč na kategórie znalostí, ktoré profil povoľuje, rovnako ako používateľa s týmto profilom.

Kľúč možno obmedziť aj na niektoré kolekcie a nastaviť mu dátum vypršania platnosti. Požiadavka mimo týchto obmedzení zlyhá: chýbajúci rozsah vráti 403 s kódom api_keys.scope a objekt, ktorý kľúč nevidí, vráti 404, presne akoby neexistoval.

Dajte každej integrácii vlastný kľúč s najužšou rolou a rozsahmi, aké potrebuje. Úloha synchronizácie, ktorá len zapisuje dokumenty, nepotrebuje admin; úloha na tvorbu prehľadov nepotrebuje rozsahy na zápis.

Vytvorte kľúč

Administrátor organizácie vytvára kľúče v Surse v časti Administration → API keys (administrácia → kľúče API) alebo cez POST /v1/api-keys s kľúčom alebo reláciou, ktorá má rolu 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"
  }'

Odpoveď obsahuje hodnotu kľúča v key. Zobrazí sa raz: Sursa si uchováva len jej hash a nemôže ju zobraziť znova. Kľúč má tvar kb_ a za ním 43 znakov; prvé znaky (prefix) sa zobrazujú v zozname kľúčov, aby ste kľúče rozlíšili.

Bez scopes dostane kľúč rozsahy svojej roly. Ak ho chcete obmedziť ešte viac, odošlite scopes. Bez expires_at platnosť kľúča nevyprší.

Uchovávajte kľúče v tajnosti

Kľúče ukladajte v správcovi tajných kľúčov alebo v premenných prostredia svojej služby, nikdy nie v zdrojovom kóde.
Kľúče používajte len zo svojich serverov. Sursa prijíma požiadavky z prehliadačov (CORS je otvorený), ale kľúč na webovej stránke vidí každý, kto ju otvorí.
Kľúč nikdy neposielajte v URL. Posielajte ho len v hlavičke Authorization.
Ak kľúč unikne, okamžite ho odvolajte a vytvorte nový.

Overte kľúč

GET /v1/me vráti kľúč, jeho rolu, platné rozsahy, dátový profil, vypršanie platnosti a limit frekvencie. Funguje s ľubovoľným platným kľúčom bez ohľadu na jeho rozsahy, preto ho používajte ako test pripojenia svojej integrácie a pri skúmaní chyby 403.

Vymeňte kľúč

Výmena (rotácia) nahradí kľúč bez zastavenia integrácie. Najrýchlejšie je vydať pre kľúč novú hodnotu: POST /v1/api-keys/{key_id}/roll vydá novú hodnotu toho istého kľúča s rovnakou rolou, rozsahmi, kolekciami a dátumom vypršania platnosti. Predchádzajúca hodnota funguje ďalej počas overlap_hours (predvolene 24 hodín, najviac 168), takže novú hodnotu medzitým stihnete nasadiť; POST /v1/api-keys/{key_id}/revoke-previous prekryv ukončí skôr.

Ak chcete kľúč namiesto toho nahradiť iným kľúčom:

Vytvorte nový kľúč s rovnakou rolou, rozsahmi a dátovým profilom.
Nasaďte nový kľúč do svojej integrácie.
Sledujte starý kľúč v časti Administration → API keys (alebo last_used v GET /v1/api-keys), kým sa prestane používať.
Starý kľúč odvolajte.

Kľúčom nastavte dátum vypršania platnosti a vymeňte ich ešte pred ním. Sursa administrátorov organizácie pred vypršaním platnosti kľúča upozorní; kľúč s vypršanou platnosťou vráti 401 s kódom api_keys.expired.

Odvolajte kľúč

Kľúč odvoláte v časti Administration → API keys alebo cez DELETE /v1/api-keys/{key_id}. Odvolanie nadobudne účinnosť do niekoľkých sekúnd na každom serveri API. Požiadavky s odvolaným kľúčom vrátia 401 s kódom auth.not_authenticated.

Kľúče vlastného zdroja

Vlastný zdroj má vlastný druh kľúča. Začína na kbsrc_, smie len zapisovať dokumenty do tohto jedného zdroja a nemôže nič čítať ani vyhľadávať. Je to najbezpečnejší kľúč, aký môžete dať integračnej platforme, napríklad Zapieru. Vytvoríte ho na stránke zdroja v sekcii API keys (kľúče API zdroja) alebo cez POST /v1/sources/{source_id}/push-keys.

Keď kľúče nie sú k dispozícii

Kľúče API sú súčasťou tarify organizácie. Ak ich tarifa nezahŕňa, vytvorenie kľúča aj každá požiadavka s kľúčom vráti 403 s kódom api_keys.feature_disabled.