# Скоупы

Скоуп — это разрешение на доступ к части данных Битрикс24 или к разделу платформы Вайбкод. При создании ключа выбирайте минимальный набор скоупов, достаточный для задачи: чем меньше прав у ключа, тем меньше последствий при его компрометации.

Скоупы выбираются в форме создания ключа двумя группами — «Битрикс24» и «Вайбкод». Минимум один скоуп обязателен. Набор скоупов Битрикс24 закрепляется за ключом в момент выпуска. Если добавить скоуп Битрикс24 в настройках уже существующего ключа, `GET /v1/me` покажет его в списке, но к данным Битрикс24 ключ продолжит обращаться с исходным набором — запросы, которым нужен новый скоуп, вернут ошибку `BITRIX_ACCESS_DENIED`. Получить новый скоуп Битрикс24 можно, только заново выпустив API-ключ или заново создав приложение (для ключа авторизации) с этим скоупом — порядок описан на странице [Создание ключа](./keys-auth.md).

Пошаговый разбор всей формы создания ключа — [Создание ключа](./keys-auth.md).

## Как выбрать скоупы под задачу

Быстрый ориентир: какие скоупы нужны под типовой сценарий приложения.

| Задача | Скоупы |
|--------|--------|
| Дашборд по сделкам, контактам, компаниям | `crm`, `user` |
| Отправка сообщений и уведомлений в чат (`POST /v1/notifications`, `POST /v1/chats/:dialogId/messages`) | `im` |
| Публикации в Живую ленту (`POST /v1/posts`) | `log` |
| Чат-бот в мессенджере портала | `imbot`, `im` |
| Управление задачами | `task`, `tasks`, `user` |
| Рабочие группы и проекты | `sonet_group` |
| Работа с файлами на Диске | `disk` |
| Интернет-магазин: заказы и каталог | `sale`, `catalog` |
| Телефония и журнал звонков | `telephony`, `call` |
| Календарь и события сотрудников | `calendar`, `user` |
| Профили сотрудников и оргструктура | `user`, `department` |
| Собственное хранилище данных приложения | `entity` |
| Бизнес-процессы и автоматизация | `bizproc` |

Если в сценарии участвует несколько модулей — укажите несколько скоупов.

## Полная таблица скоупов Битрикс24

Полный перечень скоупов Битрикс24.

| Скоуп | Что открывает |
|-------|---------------|
| `crm` | Сделки, лиды, контакты, компании, счета и другие сущности CRM |
| `task` | Задачи. Для работы с задачами выберите вместе с `tasks` |
| `tasks` | Задачи, подзадачи, чек-листы, комментарии, учёт времени. Для работы с задачами выберите вместе с `task` |
| `im` | Отправка и чтение сообщений в чатах |
| `imbot` | Регистрация и управление чат-ботами |
| `imopenlines` | Открытые линии: обращения клиентов |
| `imconnector` | Коннекторы для внешних мессенджеров (открытые линии) |
| `call` | Управление звонками и телефонией |
| `telephony` | Интеграция с внешней телефонией и управление звонками |
| `bizproc` | Запуск и управление бизнес-процессами |
| `calendar` | Доступ к календарям и событиям сотрудников |
| `timeman` | Учёт рабочего времени и контроль посещаемости |
| `catalog` | Работа с торговым каталогом и товарами |
| `sale` | Заказы, оплаты, доставки — модуль интернет-магазина |
| `lists` | Универсальные списки и элементы списков |
| `disk` | Загрузка, скачивание и управление файлами на Диске |
| `entity` | Пользовательское хранилище данных приложения |
| `user` | Профили пользователей — полный набор полей |
| `user_basic` | Профили пользователей — сокращённый набор полей |
| `user_brief` | Профили пользователей — минимальный набор полей |
| `user.userfield` | Пользовательские поля пользователей |
| `department` | Структура компании и подразделения |
| `landing` | Управление сайтами и посадочными страницами |
| `documentgenerator` | Генерация документов по шаблонам |
| `sign.b2e` | Электронная подпись документов между сотрудником и компанией |
| `sonet_group` | Рабочие группы и проекты соцсети |
| `log` | Живая лента: публикации, комментарии, реакции |
| `vote` | Работа с опросами и голосованиями |
| `ai_admin` | Администрирование AI-сервисов Битрикс24 |
| `biconnector` | Бизнес-аналитика и подключение внешних BI-систем |
| `booking` | Управление бронированиями и расписанием |
| `delivery` | Настройка и управление службами доставки |
| `pay_system` | Настройка и управление платёжными системами |
| `main` | Базовые сервисные методы портала: настройки, события |
| `placement` | Встраивание интерфейсов в разные места Битрикс24. Как привязать место — [Места встраивания](/docs/apps/placements) |
| `userfieldtype` | Регистрация собственных типов пользовательских полей |
| `humanresources` | Оргструктура: подразделения, команды, сотрудники |
| `mail` | Почтовые ящики, письма, отправители |
| `contact_center` | Контакт-центр: размещение плитки приложения (коннекторы открытых линий). Нужен для placement `CONTACT_CENTER` |

## Скоупы платформы Вайбкод

Скоупы платформы Вайбкод управляют доступом к разделам самой платформы, а не к данным Битрикс24.

| Скоуп | Что открывает |
|-------|---------------|
| `vibe:infra` | Управление серверами, тоннелями и инфраструктурой |
| `vibe:ai` | Доступ к AI-моделям платформы |
| `vibe:feedback` | Отправка обратной связи через API |
| `vibe:search` | Веб-поиск по внешним источникам через платформу |
| `vibe:storage` | Файловое хранилище платформы: загрузка и хранение объектов |

### Зарезервированные скоупы

Во вкладке «Вайбкод» формы создания ключа видны ещё три отмеченных пункта — `vibe:security`, `vibe:analytics`, `vibe:airouter`. Выбор в них недоступен, и на права ключа они не влияют: в наборе, который возвращает [`GET /v1/me`](/docs/keys-auth/me), этих строк нет.

## Платформенные скоупы отмечены заранее

В форме создания ключа все скоупы Вайбкод отмечены заранее, поэтому ключ, выпущенный без правок формы, получает полный набор:

- `vibe:infra`
- `vibe:ai`
- `vibe:search`
- `vibe:storage`
- `vibe:feedback`

Это предвыбор, а не принудительная выдача: снимите галочку — и ключ выпустится без этого права. Например, ключ только с `vibe:storage` получит доступ к объектному хранилищу и вернёт `403` на попытку создать сервер или обратиться к AI.

Сузить права после выпуска тоже можно — в настройках ключа. Но выпуск ровно нужного набора надёжнее: ключ ни секунды не существует с правами шире необходимых.

Два места, где четыре платформенных скоупа добавляются сами:

- **парный ключ приложения** (`vibe_app_`) — его набор задаёт приложение, а не форма ключа. Приложение, созданное ключом с зафиксированным набором прав, — исключение: его парный ключ получает ровно объявленное в `scopes`, и нужное `vibe:*` право там перечисляется явно, см. [Создать приложение](/docs/apps/create).
- **`POST /v1/keys` без `exactScopes`** — прежнее поведение сохранено, чтобы не менять права у уже написанных скриптов. Нужен точный набор — передайте `exactScopes: true`, см. [Менеджмент-ключи](./management-keys.md).

## Скоупы менеджмент-ключа

Менеджмент-ключ использует отдельный набор скоупов (`vibe:mgmt:keys`, `vibe:mgmt:portals`, `vibe:mgmt:feedback`) и не имеет доступа к данным Битрикс24. Полное описание — [Менеджмент-ключи](./management-keys.md).

## Смотрите также

- [Создание ключа](./keys-auth.md)
- [Быстрый старт](./quickstart.md)
- [Менеджмент-ключи](./management-keys.md)
- [Обзор API](./entity-api.md)