Обхвати на ключовете
Обхватът назовава част от API, която ключът може да извиква. Всяка операция в справочника на API
обявява единствения обхват, от който се нуждае. Заявка с ключ, който няма този обхват, се отхвърля с 403 и кода
api_keys.scope, преди нещо да бъде прочетено или променено.
Обхватите казват кои операции може да извиква ключът. Кои обекти виждат тези операции, все така решават ролята,
профилът за достъп и колекциите на ключа: ключ с cards:write и ролята viewer не може да променя карти, а ключ,
ограничен до една колекция, не вижда останалите.
Обхвати
| Обхват | Позволява |
|---|---|
cards:read | Четене на карти, колекции и папки. |
cards:write | Създаване, промяна и изтриване на карти, колекции и папки. |
search | Търсене в базата от знания (POST /v1/search). |
ask | Въпроси към асистента (POST /v1/ask, POST /v1/chat). |
import:write | Запис в собствените източници на организацията: синхронизации, пакети и изтривания, както и четене на състоянието им. За създаване на източник и ключовете му е нужен admin. |
webhooks:manage | Управление на уебхукове и четене на лентата със събития (GET /v1/webhook-events). И за двете е нужна и ролята admin. |
users:read | Четене на потребители и групи. |
users:write | Промяна на потребители и групи. |
analytics:read | Четене на аналитиката. |
audit:read | Четене на одитния дневник. |
finance:read | Четене на финансови отчети, фактури и плащания. |
catalog:read | Четене на каталога на услугите. |
files:read | Четене на генерирани файлове, например експортирани отговори. |
files:write | Промяна и изтриване на генерирани файлове. |
permissions:manage | Присвояване и отнемане на права върху обекти. |
admin | Настройките на организацията и API ключовете ѝ. Ключ с admin има и всички останали обхвати. |
По своята същност търсенето и въпросите са четене: ключ, който може само да чете, пак може да търси и да задава въпроси.
Избор на обхвати
Дайте обхватите, които интеграцията използва, и нищо повече:
| Интеграция | Обхвати |
|---|---|
| Бот за въпроси и отговори в чат инструмент | search, ask |
| Импорт от вашата система за документи | cards:write (API за карти) или import:write (собствен източник) |
| Експорт в хранилище за данни | cards:read, users:read и webhooks:manage за лентата със събития |
| Създаване на потребители от вашата система за човешки ресурси | users:write |
Подайте списъка, когато създавате ключа:
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"]}'По-ранни обхвати
Ключовете, създадени преди обхватите да бъдат разделени, продължават да работят. Техните обхвати read, write и
admin означават следните набори:
| По-ранен обхват | Означава |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | всичко от read, плюс cards:write, files:write, users:write, permissions:manage |
admin | всички обхвати |
Ключ, създаден без изрично посочени обхвати, ги получава от ролята си: admin получава admin; editor и
verifier получават write; viewer получава read.
Как да видите обхватите на ключ
GET /v1/me връща обхватите на ключа, който изпраща заявката, каквито и обхвати да има
той. За ключ, създаден без изрично зададени обхвати, това са по-ранните обхвати на ролята му, например read и
write; таблицата по-горе показва какво означават те. Когато операция се провали с api_keys.scope,
error.message посочва липсващия обхват.