# Скоупы

Скоуп — это разрешение на доступ к части данных Битрикс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` | Профили пользователей — сокращённый набор полей. Раздел `/v1/users` этим правом не открывается |
| `user_brief` | Профили пользователей — минимальный набор полей. Раздел `/v1/users` этим правом не открывается |
| `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` | Регистрация собственных типов пользовательских полей. Через API Вайбкод эти методы не проксируются — поля встроенных типов доступны в разделе [Пользовательские поля](/docs/userfields) |
| `humanresources` | Оргструктура: подразделения, команды, сотрудники |
| `mail` | Почтовые ящики, письма, отправители |
| `contact_center` | Контакт-центр: размещение плитки приложения (коннекторы открытых линий). Нужен для placement `CONTACT_CENTER` |

**Права `user_basic` и `user_brief` не заменяют `user`.** Методы раздела [Сотрудники](/docs/entities/users) — список, получение по ID, поиск, поля, профиль текущего сотрудника — принимают только полное право `user`, и ключ без него получает `403 SCOPE_DENIED`. Сокращённые права принимает [`GET /v1/workday/records`](/docs/workday/records): там достаточно одного из `user_brief`, `user_basic`, `user` вместе с `timeman`.


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

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

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

`vibe:connectors` — явное право хоста приложения; оно не добавляется вместе с обычными платформенными скоупами. Нужны действующее приложение и его персональный ключ или OAuth-ключ приложения с совпадающими владельцем и порталом. Пока функция не включена для портала, маршруты отвечают `404 ROUTE_NOT_FOUND`. Доступны только общие подключения `PORTAL`, разрешённые администратором и правами владельца ключа; доступ по сотруднику-зрителю не выдаётся, подключение и правило не создаются.

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

Во вкладке «Вайбкод» формы создания ключа видны ещё три отмеченных пункта — `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.

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

Ключ, выданный стороннему приложению через [Partner Connect](/docs/partner-connect), — исключение из обоих правил ниже: платформенные права ему не добавляются никогда, он несёт ровно то, что пользователь подтвердил на странице согласия. `vibe:ai` приложение запрашивает само, `vibe:storage` ему не выдаётся, остальные платформенные права ему выдаёт платформенный администратор.

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

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

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

Менеджмент-ключ использует отдельный набор скоупов (`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)
