Области ключа
Область обозначает часть 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.