Atslēgu tvērumi

Tvērums nosauc API daļu, kuru atslēga drīkst izsaukt. Katra API rokasgrāmatas operācija norāda vienu tvērumu, kas tai vajadzīgs. Pieprasījums ar atslēgu, kurai šā tvēruma nav, tiek noraidīts ar 403 un kodu api_keys.scope, pirms kaut kas tiek nolasīts vai mainīts.

Tvērumi nosaka, kuras operācijas atslēga drīkst izsaukt. Kurus objektus šīs operācijas redz, joprojām nosaka atslēgas loma, datu profils un kolekcijas: atslēga ar cards:write un lomu viewer nevar mainīt kartītes, bet atslēga, kas ierobežota ar vienu kolekciju, neredz pārējās.

Tvērumi

Tvērums	Atļauj
`cards:read`	Lasīt kartītes, kolekcijas un mapes.
`cards:write`	Izveidot, mainīt un dzēst kartītes, kolekcijas un mapes.
`search`	Meklēt zināšanu bāzē (`POST /v1/search`).
`ask`	Uzdot jautājumus asistentam (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Rakstīt organizācijas pielāgotajos avotos: sinhronizācijas, partijas un dzēšana, kā arī to stāvokļa lasīšana. Avota un tā atslēgu izveidei vajadzīgs `admin`.
`webhooks:manage`	Pārvaldīt webhook galapunktus un lasīt notikumu plūsmu (`GET /v1/webhook-events`). Abām darbībām vajadzīga arī loma `admin`.
`users:read`	Lasīt lietotājus un grupas.
`users:write`	Mainīt lietotājus un grupas.
`analytics:read`	Lasīt analītiku.
`audit:read`	Lasīt audita žurnālu.
`finance:read`	Lasīt finanšu pārskatus, rēķinus un maksājumus.
`catalog:read`	Lasīt pakalpojumu katalogu.
`files:read`	Lasīt ģenerētos failus, piemēram, eksportētas atbildes.
`files:write`	Mainīt un dzēst ģenerētos failus.
`permissions:manage`	Piešķirt un atsaukt atļaujas objektiem.
`admin`	Organizācijas iestatījumi un tās API atslēgas. Atslēgai ar `admin` ir arī visi pārējie tvērumi.

Meklēšana un jautājumi pēc būtības ir lasīšana: atslēga, kas drīkst tikai lasīt, var arī meklēt un uzdot jautājumus.

Tvērumu izvēle

Piešķiriet tos tvērumus, kurus integrācija izmanto, un neko vairāk:

Integrācija	Tvērumi
Jautājumu un atbilžu robots tērzēšanas rīkā	`search`, `ask`
Imports no jūsu dokumentu sistēmas	`cards:write` (kartīšu API) vai `import:write` (pielāgots avots)
Eksports uz datu noliktavu	`cards:read`, `users:read` un `webhooks:manage` notikumu plūsmai
Lietotāju izveide no jūsu personāla vadības sistēmas	`users:write`

Nododiet sarakstu, kad izveidojat atslēgu:

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

Agrākie tvērumi

Atslēgas, kas izveidotas pirms tvērumu sadalīšanas, turpina darboties. To tvērumi read, write un admin apzīmē šādas kopas:

Agrākais tvērums	Nozīmē
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	viss no `read`, kā arī `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	visi tvērumi

Atslēga, kas izveidota bez skaidri norādītiem tvērumiem, tos saņem no savas lomas: admin saņem admin; editor un verifier saņem write; viewer saņem read.

Atslēgas tvērumu apskate

GET /v1/me atgriež tās atslēgas tvērumus, ar kuru sūtīts pieprasījums, lai kādi tvērumi tai būtu. Atslēgai, kas izveidota bez skaidri norādītiem tvērumiem, tie ir tās lomas agrākie tvērumi, piemēram, read un write; augstāk esošā tabula parāda, ko tie nozīmē. Ja operācija neizdodas ar api_keys.scope, error.message norāda tvērumu, kura trūka.