🔑 Scopes (права доступа)
Что это. Scopes — права API-ключа: они определяют, какие методы публичного API можно вызывать этим ключом.
Когда нужно. Права выбираются один раз, при создании ключа, и после этого не меняются — поэтому набор стоит продумать заранее.
Для вызова метода ключ должен содержать все требуемые для этого метода scopes — иначе сервер вернёт 403 Forbidden с текстом Insufficient scopes for this operation.
Если ключу не выдано ни одного права, любой запрос по нему завершится 401 Unauthorized с текстом API key has no scopes.
Где находится
Настройки проекта → вкладка «API» → «Создать ключ» → блок «Права доступа (scopes)».
Это не список строк, а матрица «ресурс × действие»: строки — ресурсы, колонки — четыре действия. Над матрицей есть кнопка «Выбрать все».
Отметить нужно хотя бы один пункт, иначе форма покажет «Выберите хотя бы один scope».
📷 Скриншот: блок «Права доступа (scopes)» в окне «Создание API-ключа» (будет добавлен).
🧩 Как устроено название
Имя скоупа собирается по схеме РЕСУРС_ДЕЙСТВИЕ: часть после последнего подчёркивания — действие, всё, что до него, — ресурс. Поэтому составные названия ресурсов не разваливаются: KNOWLEDGE_BASE_READ — это ресурс KNOWLEDGE_BASE и действие READ.
Действий всегда четыре:
| Действие | Скоуп | Подпись в форме |
|---|---|---|
| Чтение | <РЕСУРС>_READ | «Чтение» |
| Запись | <РЕСУРС>_WRITE | «Запись» |
| Удаление | <РЕСУРС>_DELETE | «Удаление» |
| Управление | <РЕСУРС>_MANAGE | «Управление» |
Что именно попадает в «Управление», зависит от ресурса: это отдельные операции вроде запуска и остановки бота или массового импорта документов, а не «всё сразу».
<РЕСУРС>_MANAGE не включает в себя <РЕСУРС>_READ, а _WRITE не включает _DELETE. Отмечайте все действия, которые нужны интеграции, по отдельности.
📋 Ресурсы
Всего опубликовано 52 скоупа: у каждого ресурса четыре действия — _READ, _WRITE, _DELETE, _MANAGE. В таблице ниже — основные ресурсы, соответствующие разделам API; полный каталог отдаёт сервер, поэтому список может быть шире:
| Ресурс | Скоупы | Что покрывает |
|---|---|---|
BOTS | BOTS_READ, BOTS_WRITE, BOTS_DELETE, BOTS_MANAGE | Боты каналов: список и сведения, создание и изменение, удаление, запуск и остановка |
USERS | USERS_* | Участники проекта и их роли |
MESSAGES | MESSAGES_* | Сообщения переписки |
KNOWLEDGE_BASE | KNOWLEDGE_BASE_* | Папки и документы базы знаний, поиск, загрузка файлов, массовый импорт |
AI | AI_* | AI-функции платформы |
FLOWS | FLOWS_* | Сценарии и их запуски |
METRICS | METRICS_* | Дашборды и данные виджетов аналитики |
SETTINGS | SETTINGS_* | Настройки проекта |
SHORT_LINKS | SHORT_LINKS_* | Короткие ссылки |
STORAGE | STORAGE_* | Файлы вложений в хранилище |
TAGS | TAGS_* | Теги и их привязка к объектам |
TECH_SUPPORT | TECH_SUPPORT_* | Обращения и настройки поддержки |
WIDGETS | WIDGETS_* | Виджет для сайта |
Каталог ресурсов и действий отдаёт сервер, а форма создания ключа рисует его сама. Если в форме появился ресурс, которого нет в таблице выше, ориентируйтесь на форму и на Swagger UI — они всегда актуальнее документации.
Каталог прав шире, чем набор опубликованных маршрутов: некоторые скоупы объявлены, но пока не используются ни одним публичным методом. Выдача такого права ничего не ломает, но и ничего не даёт. Проверить, какие права действительно нужны, можно в описании операции в Swagger UI — блок Required scopes.
Как подобрать права
- Выпишите список операций, которые будет делать интеграция.
- Найдите каждую операцию в Swagger UI и посмотрите блок Required scopes.
- Отметьте в форме только эти пункты.
- После выпуска ключа проверьте интеграцию целиком: не хватит одного права — метод вернёт
403 Insufficient scopes for this operation.
Примеры типовых наборов:
| Задача интеграции | Достаточно прав |
|---|---|
| Синхронизировать базу знаний из внешней системы | KNOWLEDGE_BASE_MANAGE (для массового импорта), при точечных правках дополнительно KNOWLEDGE_BASE_READ и KNOWLEDGE_BASE_WRITE |
| Только выгружать данные для отчёта | <РЕСУРС>_READ нужных разделов |
| Управлять ботами из своей панели | BOTS_READ и BOTS_MANAGE, при создании и изменении — BOTS_WRITE |
Ограничения
- Права выпущенного ключа изменить нельзя. Чтобы поменять набор, ключ отзывают и выпускают новый — секрет при этом меняется.
- Срок действия ключа тоже не редактируется — меняются только имя и описание.
- Скоупы не привязаны к роли участника: ключ с правом
USERS_MANAGEменяет роли независимо от того, кто его выпустил. Поэтому выдавать ключ с широкими правами так же ответственно, как выдавать доступ администратора. - Права не ограничивают лимит запросов: он единый — 1000 запросов в минуту на ключ.
Один ключ — одна интеграция и минимально необходимый набор прав. Такой ключ безопаснее отзывать: не придётся переключать соседние сервисы.
Кто что может
| Действие | Минимальная роль |
|---|---|
| Посмотреть, какие права выданы ключу | Администратор |
| Выбрать права при создании ключа | Администратор |
| Изменить права у существующего ключа | Невозможно ни для кого — только выпуск нового ключа |