Raktų apimtys

Apimtis nurodo API dalį, kurią raktas gali kviesti. Kiekviena API žinyno operacija nurodo vieną jai reikalingą apimtį. Užklausa su raktu, kuris jos neturi, atmetama su 403 ir kodu api_keys.scope dar prieš ką nors nuskaitant ar pakeičiant.

Apimtys nurodo, kurias operacijas raktas gali kviesti. Kuriuos objektus tos operacijos mato, vis tiek lemia rakto vaidmuo, duomenų profilis ir rinkiniai: raktas su cards:write ir vaidmeniu viewer negali keisti kortelių, o vienu rinkiniu apribotas raktas nemato kitų.

Apimtys

Apimtis	Leidžia
`cards:read`	Skaityti korteles, rinkinius ir aplankus.
`cards:write`	Kurti, keisti ir trinti korteles, rinkinius ir aplankus.
`search`	Ieškoti žinių bazėje (`POST /v1/search`).
`ask`	Klausti asistento (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Rašyti į organizacijos pasirinktinius šaltinius: sinchronizacijos, partijos ir ištrynimai, taip pat skaityti jų būseną. Šaltiniui ir jo raktams sukurti reikia `admin`.
`webhooks:manage`	Valdyti webhook galinius taškus ir skaityti įvykių juostą (`GET /v1/webhook-events`). Abiem reikia ir vaidmens `admin`.
`users:read`	Skaityti naudotojus ir grupes.
`users:write`	Keisti naudotojus ir grupes.
`analytics:read`	Skaityti analitiką.
`audit:read`	Skaityti audito žurnalą.
`finance:read`	Skaityti finansines ataskaitas, sąskaitas faktūras ir mokėjimus.
`catalog:read`	Skaityti paslaugų katalogą.
`files:read`	Skaityti sugeneruotus failus, pavyzdžiui, eksportuotus atsakymus.
`files:write`	Keisti ir trinti sugeneruotus failus.
`permissions:manage`	Suteikti ir atšaukti leidimus objektams.
`admin`	Organizacijos nustatymai ir jos API raktai. Raktas su `admin` turi ir visas kitas apimtis.

Paieška ir klausimai pagal prasmę yra skaitymas: raktas, kuriam leidžiama tik skaityti, vis tiek gali ieškoti ir klausti.

Kaip pasirinkti apimtis

Suteikite tik tas apimtis, kurias integracija naudoja:

Integracija	Apimtys
Klausimų ir atsakymų botas pokalbių įrankyje	`search`, `ask`
Importas iš jūsų dokumentų sistemos	`cards:write` (kortelių API) arba `import:write` (pasirinktinis šaltinis)
Eksportas į duomenų sandėlį	`cards:read`, `users:read` ir `webhooks:manage` įvykių juostai
Naudotojų kūrimas iš jūsų personalo sistemos	`users:write`

Sąrašą perduokite, kai kuriate raktą:

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

Ankstesnės apimtys

Raktai, sukurti prieš išskaidant apimtis, toliau veikia. Jų apimtys read, write ir admin reiškia šiuos rinkinius:

Ankstesnė apimtis	Reiškia
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	viskas, kas yra `read`, ir dar `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	visos apimtys

Raktas, sukurtas be aiškiai nurodytų apimčių, jas gauna pagal savo vaidmenį: admin gauna admin; editor ir verifier gauna write; viewer gauna read.

Rakto apimčių peržiūra

GET /v1/me grąžina užklausą siunčiančio rakto apimtis, kad ir kokias apimtis jis turėtų. Raktui, sukurtam be aiškiai nurodytų apimčių, tai ankstesnės jo vaidmens apimtys, pavyzdžiui, read ir write; lentelėje aukščiau parodyta, ką jos reiškia. Kai operacija nepavyksta su api_keys.scope, error.message nurodo trūkstamą apimtį.