Rozsahy klíče

Rozsah pojmenovává část API, kterou klíč smí volat. Každá operace v referenci API uvádí jeden rozsah, který potřebuje. Požadavek s klíčem, kterému tento rozsah chybí, se odmítne s 403 a kódem api_keys.scope dřív, než se cokoli přečte nebo změní.

Rozsahy určují, které operace smí klíč volat. O tom, které objekty tyto operace uvidí, dál rozhoduje role, datový profil a kolekce klíče: klíč s cards:write a rolí viewer nemůže měnit karty a klíč omezený na jednu kolekci nevidí ostatní.

Rozsahy

Rozsah	Povoluje
`cards:read`	Číst karty, kolekce a složky.
`cards:write`	Vytvářet, měnit a mazat karty, kolekce a složky.
`search`	Vyhledávat ve znalostní bázi (`POST /v1/search`).
`ask`	Klást otázky asistentovi (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Zapisovat do vlastních zdrojů organizace: synchronizace, dávky a mazání, a číst jejich stav. Vytvoření zdroje a jeho klíčů vyžaduje `admin`.
`webhooks:manage`	Spravovat webhooky a číst kanál událostí (`GET /v1/webhook-events`). Obojí navíc vyžaduje roli `admin`.
`users:read`	Číst uživatele a skupiny.
`users:write`	Měnit uživatele a skupiny.
`analytics:read`	Číst analytiku.
`audit:read`	Číst auditní protokol.
`finance:read`	Číst finanční výkazy, faktury a platby.
`catalog:read`	Číst katalog služeb.
`files:read`	Číst vygenerované soubory, například exportované odpovědi.
`files:write`	Měnit a mazat vygenerované soubory.
`permissions:manage`	Přiřazovat a odebírat oprávnění k objektům.
`admin`	Nastavení organizace a jejích klíčů API. Klíč s `admin` má i všechny ostatní rozsahy.

Vyhledávání a otázky jsou svou povahou čtení: klíč, který smí jen číst, může přesto vyhledávat a klást otázky.

Volba rozsahů

Přidělte rozsahy, které integrace používá, a nic dalšího:

Integrace	Rozsahy
Bot pro otázky a odpovědi v chatovacím nástroji	`search`, `ask`
Import z vašeho systému dokumentů	`cards:write` (API karet) nebo `import:write` (vlastní zdroj)
Export do datového skladu	`cards:read`, `users:read` a `webhooks:manage` pro kanál událostí
Zřizování uživatelů z vašeho personálního systému	`users:write`

Seznam předejte při vytváření klíče:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

Dřívější rozsahy

Klíče vytvořené před rozdělením rozsahů dál fungují. Jejich rozsahy read, write a admin zastupují tyto sady:

Dřívější rozsah	Znamená
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	vše z `read` a navíc `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	všechny rozsahy

Klíč vytvořený bez výslovně uvedených rozsahů je získá ze své role: admin dostane admin; editor a verifier dostanou write; viewer dostane read.

Zjištění rozsahů klíče

GET /v1/me vrací rozsahy klíče, který požadavek odesílá, bez ohledu na to, jaké rozsahy má. U klíče vytvořeného bez výslovně uvedených rozsahů jde o dřívější rozsahy jeho role, například read a write; co zahrnují, ukazuje tabulka výše. Když operace selže s api_keys.scope, error.message uvádí rozsah, který chyběl.