Області доступу ключа
Область доступу називає частину 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 для стрічки подій |
| Створення користувачів із вашої HR-системи | 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
називає область доступу, якої бракувало.