Klíče API a rozsahy

Každý požadavek na Sursa API se odesílá s klíčem API vaší organizace. Klíč patří organizaci, ne člověku: funguje dál i poté, co zaměstnanec, který ho vytvořil, odejde, a to, co klíč smí, je nastaveno přímo na něm.

Co klíč smí

O tom, co požadavek s klíčem smí vidět a měnit, rozhodují tři nastavení klíče. Každé z nich ostatní jen dále zužuje.

Nastavení	Co určuje
Role	`admin`, `editor`, `verifier` nebo `viewer` – stejné role, jaké mají lidé. Klíč smí to, co uživatel s touto rolí.
Rozsahy	Které části API smí klíč volat, například `cards:read` nebo `webhooks:manage`. Viz Rozsahy klíče.
Datový profil	Volitelný. Omezuje klíč na kategorie znalostí, které profil povoluje, stejně jako uživatele s tímto profilem.

Klíč lze také omezit na některé kolekce a nastavit mu datum vypršení platnosti. Požadavek mimo tato omezení selže: chybějící rozsah vrátí 403 s kódem api_keys.scope a objekt, který klíč nevidí, vrátí 404, přesně jako by neexistoval.

Každé integraci dejte vlastní klíč s co nejužší rolí a rozsahy, které potřebuje. Synchronizační úloha, která jen zapisuje dokumenty, nepotřebuje admin; úloha pro reporty nepotřebuje rozsahy pro zápis.

Vytvoření klíče

Administrátor organizace vytváří klíče v Surse v Administration → API keys (administrace → klíče API) nebo pomocí POST /v1/api-keys s klíčem nebo relací, které mají roli 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"
  }'

Odpověď obsahuje hodnotu klíče v key. Zobrazí se jen jednou: Sursa si uchovává pouze její hash a znovu ji zobrazit nemůže. Klíč má tvar kb_ a za ním 43 znaků; první znaky (prefix) se zobrazují v seznamu klíčů, aby bylo možné klíče od sebe rozlišit.

Bez scopes dostane klíč rozsahy své role. Chcete-li ho omezit ještě víc, předejte scopes. Bez expires_at platnost klíče nevyprší.

Uchovávejte klíče v tajnosti

Klíče ukládejte do správce tajných klíčů nebo do proměnných prostředí své služby, nikdy do zdrojového kódu.
Klíče používejte jen ze svých serverů. Sursa přijímá požadavky z prohlížečů (CORS je otevřený), ale klíč na webové stránce vidí každý, kdo ji otevře.
Nikdy neposílejte klíč v URL. Posílejte ho jen v hlavičce Authorization.
Pokud klíč unikne, okamžitě ho odvolejte a vytvořte nový.

Kontrola klíče

GET /v1/me vrací klíč, jeho roli, platné rozsahy, datový profil, vypršení platnosti a limit četnosti. Funguje s jakýmkoli platným klíčem bez ohledu na jeho rozsahy, takže ho používejte jako test připojení své integrace a při zjišťování příčiny 403.

Obměna klíče

Obměna (rotace) nahradí klíč, aniž by se integrace zastavila. Nejrychleji klíč obměníte operací POST /v1/api-keys/{key_id}/roll: vydá novou hodnotu téhož klíče se stejnou rolí, rozsahy, kolekcemi a vypršením platnosti. Předchozí hodnota funguje dál po dobu overlap_hours (ve výchozím stavu 24 hodin, nejvýše 168), takže mezitím můžete novou hodnotu nasadit; POST /v1/api-keys/{key_id}/revoke-previous překryv ukončí dříve.

Chcete-li klíč místo toho nahradit jiným klíčem:

Vytvořte nový klíč se stejnou rolí, rozsahy a datovým profilem.
Nasaďte nový klíč do své integrace.
Sledujte starý klíč v Administration → API keys (nebo last_used v GET /v1/api-keys), dokud se přestane používat.
Odvolejte starý klíč.

Klíčům nastavujte datum vypršení platnosti a obměňujte je dřív, než nastane. Sursa administrátory organizace před vypršením platnosti klíče upozorní; klíč s prošlou platností vrací 401 s kódem api_keys.expired.

Odvolání klíče

Klíč odvoláte v Administration → API keys nebo pomocí DELETE /v1/api-keys/{key_id}. Odvolání začne platit během několika sekund na všech serverech API. Požadavky s odvolaným klíčem vracejí 401 s kódem auth.not_authenticated.

Klíče vlastního zdroje

Vlastní zdroj má vlastní druh klíče. Začíná na kbsrc_, může jen zapisovat dokumenty do tohoto jednoho zdroje a nemůže nic číst ani vyhledávat. Je to nejbezpečnější klíč pro integrační platformu, jako je Zapier. Vytvoříte ho na stránce zdroje v sekci API keys (klíče API zdroje) nebo pomocí POST /v1/sources/{source_id}/push-keys.

Když klíče nejsou k dispozici

Klíče API jsou součástí tarifu organizace. Pokud je tarif nezahrnuje, vytvoření klíče i každý požadavek s klíčem vrátí 403 s kódem api_keys.feature_disabled.