Доступные скоупы Битрикс24

Скоуп — это код группы методов. Он определяет, к каким инструментам Битрикс24 приложение или вебхук может обращаться через REST API. Как подобрать скоупы под сценарий приложения и чем скоуп отличается от прав пользователя — в статье Права на методы и скоупы.

Быстрый переход: коды скоупов

Где указывается скоупГде указывается скоуп

Для приложения скоупы выбирают при добавлении, а место зависит от вида решения.

• Тиражное решение добавляют в кабинете разработчика, в разделе Мои приложения > Добавить приложение. Скоупы указывают в технических характеристиках, как разделы системы, с которыми работает приложение. Порядок описан в статье Как добавить решение в кабинет разработчика.
• Локальное приложение добавляют в Битрикс24, в разделе Приложения > Разработчикам. Порядок описан в статье Локальные приложения.

Для вебхука скоупы выбирают при создании, на шаге Укажите права доступа. Запросы выполняются в рамках выбранных скоупов и с правами сотрудника, который создал вебхук. Подробнее — в статье Входящие и исходящие вебхуки.

Что будет, если вызвать метод вне выданного скоупаЧто будет, если вызвать метод вне выданного скоупа

Если приложение или вебхук вызовет метод, скоуп которого не выдан, Битрикс24 вернет ошибку insufficient_scope и не выполнит запрос. Ответ на вызов от приложения:

{
    "error": "insufficient_scope",
    "error_description": "The request requires higher privileges than provided by the access token"
}

У вебхука отличается только error_description — в нем будет provided by the webhook token.

Чтобы вызов прошел, добавьте нужный скоуп в настройки приложения или вебхука. Остальные системные ошибки собраны в статье Коды ошибок.

Когда одного скоупа недостаточноКогда одного скоупа недостаточно

Часть методов работает только в контексте приложения. При вызове такого метода вебхуком Битрикс24 вернет ошибку WRONG_AUTH_TYPE с пояснением Application context required. Так ведет себя, например, метод placement.bind.

Коды скоуповКоды скоупов

Служебные скоупыСлужебные скоупы

rest.developer — служебный скоуп Битрикс24 Вайбкод. Он выдается системным вебхукам, которые Вайбкод создает для синхронизации приложений и AI-агентов с каталогом Битрикс24.