🔑 Scopes (права доступа)
Что это. Scopes — права API-ключа: они определяют, какие методы публичного API можно вызывать этим ключом.
Когда нужно. Права выбираются один раз, при создании ключа, и после этого не меняются — поэтому набор стоит продумать заранее.
Для вызова метода ключ должен содержать все требуемые для этого метода scopes — иначе сервер вернёт 403 Forbidden с текстом Insufficient scopes for this operation.
Если ключу не выдано ни одного права, любой запрос по нему завершится 401 Unauthorized с текстом API key has no scopes.
Где находится
Настройки проекта → вкладка «API» → «Создать ключ» → блок «Права доступа (scopes)».
Это не список строк, а матрица «ресурс × действие»: строки — ресурсы, колонки — четыре действия и колонка «Все», которая отмечает все действия ресурса сразу. Под матрицей есть флажок «Выбрать все». Если список прав не загрузился, форма покажет «Не удалось загрузить список прав. Попробуйте позже.»
Пока не отмечен хотя бы один пункт, кнопка «Создать ключ» неактивна.
📷 Скриншот: блок «Права доступа (scopes)» в окне «Создание API-ключа» (будет добавлен).
🧩 Как устроено название
Имя скоупа собирается по схеме РЕСУРС_ДЕЙСТВИЕ: часть после последнего подчёркивания — действие, всё, что до него, — ресурс. Поэтому составные названия ресурсов не разваливаются: KNOWLEDGE_BASE_READ — это ресурс KNOWLEDGE_BASE и действие READ.
Действий всегда четыре:
| Действие | Скоуп | Подпись в форме |
|---|---|---|
| Чтение | <РЕСУРС>_READ | «Чтение» |
| Запись | <РЕСУРС>_WRITE | «Запись» |
| Удаление | <РЕСУРС>_DELETE | «Удаление» |
| Управление | <РЕСУРС>_MANAGE | «Управление» |
Что именно попадает в «Управление», зависит от ресурса: это отдельные операции вроде запуска и остановки бота или массового импорта документов, а не «всё сразу». Сейчас «Управление» что-то открывает только у четырёх ресурсов:
| Ресурс | Что даёт _MANAGE |
|---|---|
BOTS | Запуск и остановка ботов |
FLOWS | Прямой запуск сценария (POST /v1/flow/executions/start) — см. Сценарии в API |
KNOWLEDGE_BASE | Массовый импорт, массовые удаление и перенос документов и папок |
USERS | Просмотр и смена ролей участника через /v1/person-profile/users/{userId}/roles |
У AI, MESSAGES, METRICS, SETTINGS, STORAGE, TAGS, TECH_SUPPORT и WIDGETS право «Управление» пока ничего не открывает.
<РЕСУРС>_MANAGE не включает в себя <РЕСУРС>_READ, а _WRITE не включает _DELETE. Отмечайте все действия, которые нужны интеграции, по отдельности.
📋 Ресурсы
Всего 48 скоупов: ресурсов 12, у каждого четыре действия — _READ, _WRITE, _DELETE, _MANAGE. В форме ресурсы подписаны по-русски, в колонке «Права» списка ключей видны коды:
| Ресурс | Подпись в форме | Скоупы | Что покрывает |
|---|---|---|---|
BOTS | Боты | BOTS_READ, BOTS_WRITE, BOTS_DELETE, BOTS_MANAGE | Боты каналов: список и сведения, создание и изменение, удаление, запуск и остановка |
USERS | Пользователи | USERS_* | Участники проекта и их роли, группы, приглашения, персоны (включая связку с каналами и слияние), подтверждение связки по коду или ссылке, профиль проекта и чтение его настроек (/v1/person-profile/settings). ⚠️ Права этого ресурса по силе равны правам администратора — см. Ограничения |
MESSAGES | Сообщения | MESSAGES_* | Сообщения переписки |
KNOWLEDGE_BASE | База знаний | KNOWLEDGE_BASE_* | Папки и документы базы знаний, поиск, загрузка файлов, массовые операции и массовый импорт |
AI | ИИ | AI_* | AI-функции платформы: классификация, извлечение данных, генерация, модерация, RAG, саммари, перевод. Все методы требуют AI_WRITE |
FLOWS | Сценарии | FLOWS_* | Сценарии, их версии и запуски, вебхук-триггер |
METRICS | Метрики | METRICS_* | Дашборды и данные виджетов аналитики |
SETTINGS | Настройки | SETTINGS_* | Чтение настроек проекта (SETTINGS_READ). Менять настройки по API-ключу нельзя |
STORAGE | Хранилище | STORAGE_* | Файлы вложений в хранилище |
TAGS | Теги | TAGS_* | Теги и их привязка к объектам |
TECH_SUPPORT | Поддержка | TECH_SUPPORT_* | Обращения поддержки: списки, статус, приоритет, линия, история, сообщения; шаблоны ответов; AI-подсказки |
WIDGETS | Виджеты | WIDGETS_* | Виджет для сайта: сам виджет, его вид и тексты, домены сайта и HMAC-секреты |
Каталог прав шире, чем набор опубликованных маршрутов: некоторые скоупы объявлены, но пока не используются ни одним публичным методом. Выдача такого права ничего не ломает, но и ничего не даёт. Сейчас не используются: AI_READ, AI_DELETE, AI_MANAGE, MESSAGES_MANAGE, METRICS_MANAGE, SETTINGS_WRITE, SETTINGS_DELETE, SETTINGS_MANAGE, STORAGE_DELETE, STORAGE_MANAGE, TAGS_MANAGE, TECH_SUPPORT_MANAGE, WIDGETS_MANAGE. Все методы AI требуют AI_WRITE. Проверить, какие права действительно нужны, можно в описании операции в Swagger UI — блок Required scopes.
Как подобрать права
- Выпишите список операций, которые будет делать интеграция.
- Найдите каждую операцию в Swagger UI и посмотрите блок Required scopes.
- Отметьте в форме только эти пункты.
- После выпуска ключа проверьте интеграцию целиком: не хватит одного права — метод вернёт
403 Insufficient scopes for this operation.
Примеры типовых наборов:
| Задача интеграции | Достаточно прав |
|---|---|
| Синхронизировать базу знаний из внешней системы | KNOWLEDGE_BASE_MANAGE (массовый импорт и массовые операции), при точечных правках дополнительно KNOWLEDGE_BASE_READ и KNOWLEDGE_BASE_WRITE, для удаления отдельного документа или папки — KNOWLEDGE_BASE_DELETE |
| Только выгружать данные для отчёта | <РЕСУРС>_READ нужных разделов. Исключения: данные дашбордов и виджетов аналитики и /v1/metrics/query — METRICS_WRITE, пакетное чтение тегов — TAGS_WRITE, роли участника — USERS_MANAGE, любые методы AI — AI_WRITE. Проверяйте блок Required scopes в Swagger UI |
| Управлять ботами из своей панели | BOTS_READ и BOTS_MANAGE, при создании и изменении — BOTS_WRITE |
| Запускать сценарии из своей системы | FLOWS_WRITE для вебхук-триггера, FLOWS_MANAGE для прямого запуска, FLOWS_READ — чтобы следить за запусками |
| Подключить ИИ-клиент (Claude Code, Cursor, VS Code, Codex) | Пресет «ИИ-клиент: только чтение» или «ИИ-клиент: оператор» — включите переключатель «Для ИИ-клиента (MCP)», см. Ключи и права для MCP |
Ограничения
- Права выпущенного ключа изменить нельзя. Чтобы поменять набор, ключ отзывают и выпускают новый — секрет при этом меняется. Режим «Доступ через MCP», в отличие от прав, у выпущенного ключа меняется.
- Срок действия ключа тоже не редактируется — меняются только имя и описание.
- Скоупы не привязаны к роли участника. Ключ меняет роли участников уже с правом
USERS_WRITE(PATCH /v1/person-profile/role/{userId}/roles), а сUSERS_MANAGEещё читает и меняет их через/v1/person-profile/users/{userId}/roles. С правомUSERS_DELETEключ удаляет участников, группы и персоны. Удалить сам проект по ключу нельзя: ключ действует с правами не выше администратора. Такие права выдавайте только доверенным интеграциям. - Права не ограничивают лимит запросов: он единый — 1000 запросов в минуту на ключ.
Один ключ — одна интеграция и минимально необходимый набор прав. Такой ключ безопаснее отзывать: не придётся переключать соседние сервисы.
Кто что может
| Действие | Минимальная роль |
|---|---|
| Посмотреть, какие права выданы ключу | Администратор |
| Выбрать права при создании ключа | Администратор |
| Изменить права у существующего ключа | Невозможно ни для кого — только выпуск нового ключа |
REST API · База знаний в API · Сценарии в API · Ключи и права для MCP · API Fixorix