Rozsahy kľúča

Rozsah pomenúva časť API, ktorú kľúč smie volať. Každá operácia v referencii API uvádza jeden rozsah, ktorý potrebuje. Požiadavka s kľúčom, ktorý ho nemá, sa odmietne so 403 a kódom api_keys.scope ešte predtým, ako sa čokoľvek prečíta alebo zmení.

Rozsahy určujú, ktoré operácie kľúč smie volať. O tom, ktoré objekty tieto operácie vidia, naďalej rozhodujú rola kľúča, dátový profil a kolekcie: kľúč s cards:write a rolou viewer nemôže meniť karty a kľúč obmedzený na jednu kolekciu nevidí ostatné.

Rozsahy

Rozsah	Povoľuje
`cards:read`	Čítať karty, kolekcie a priečinky.
`cards:write`	Vytvárať, meniť a mazať karty, kolekcie a priečinky.
`search`	Prehľadávať bázu znalostí (`POST /v1/search`).
`ask`	Klásť otázky asistentovi (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Zapisovať do vlastných zdrojov organizácie: synchronizácie, dávky a vymazania, a čítať ich stav. Vytvorenie zdroja a jeho kľúčov vyžaduje `admin`.
`webhooks:manage`	Spravovať webhooky a čítať kanál udalostí (`GET /v1/webhook-events`). Obe vyžadujú aj rolu `admin`.
`users:read`	Čítať používateľov a skupiny.
`users:write`	Meniť používateľov a skupiny.
`analytics:read`	Čítať analytiku.
`audit:read`	Čítať auditný log.
`finance:read`	Čítať finančné prehľady, faktúry a platby.
`catalog:read`	Čítať katalóg služieb.
`files:read`	Čítať vygenerované súbory, napríklad exportované odpovede.
`files:write`	Meniť a mazať vygenerované súbory.
`permissions:manage`	Priraďovať a odoberať oprávnenia k objektom.
`admin`	Nastavenia organizácie a jej kľúče API. Kľúč s `admin` má aj všetky ostatné rozsahy.

Vyhľadávanie a otázky sú svojou podstatou čítanie: kľúč, ktorý smie len čítať, môže aj vyhľadávať a klásť otázky.

Výber rozsahov

Priraďte rozsahy, ktoré integrácia používa, a nič iné:

Integrácia	Rozsahy
Bot na otázky a odpovede v chatovacom nástroji	`search`, `ask`
Import z vášho systému dokumentov	`cards:write` (API kariet) alebo `import:write` (vlastný zdroj)
Export do dátového skladu	`cards:read`, `users:read` a `webhooks:manage` pre kanál udalostí
Zakladanie používateľov z vášho personálneho systému	`users:write`

Zoznam odovzdajte pri vytváraní kľúča:

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"]}'

Staršie rozsahy

Kľúče vytvorené pred rozdelením rozsahov fungujú ďalej. Ich rozsahy read, write a admin zastupujú tieto sady:

Starší rozsah	Znamená
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	všetko z `read` a navyše `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	všetky rozsahy

Kľúč vytvorený bez výslovne uvedených rozsahov ich dostane podľa svojej roly: admin dostane admin; editor a verifier dostanú write; viewer dostane read.

Ako zistiť rozsahy kľúča

GET /v1/me vráti rozsahy kľúča, ktorý požiadavku posiela, bez ohľadu na to, aké rozsahy má. Pri kľúči vytvorenom bez výslovne uvedených rozsahov sú to staršie rozsahy jeho roly, napríklad read a write; tabuľka vyššie ukazuje, čo znamenajú. Keď operácia zlyhá s api_keys.scope, error.message uvádza rozsah, ktorý chýbal.