Доступ к методам REST Битрикс24 проверяется на двух уровнях: scope (какие разделы API разрешены приложению или вебхуку) и права пользователя, от имени которого выполняется запрос. Даже при верном scope метод откажет, если у пользователя нет прав на конкретный объект.
Два уровня проверки прав
Многие ошибки доступа возникают из-за непонимания, что проверок именно две и они независимы:
- Scope — набор разделов API, к которым допущено приложение или вебхук (crm, task, user, disk, im и т. д.). Если метод вне scope, придёт
insufficient_scopeилиERROR_METHOD_NOT_FOUND. - Права пользователя — роль и права того сотрудника, от чьего имени идёт запрос. Даже с нужным scope нельзя увидеть чужую сделку, если права CRM это запрещают.
Что такое scope
Scope — это перечень прав на разделы REST. При создании вебхука или регистрации приложения вы отмечаете нужные области. Проверить фактически выданные права можно методом scope, а полный список возможных — scope?full=true.
| Scope | Что открывает |
|---|---|
crm | Сделки, лиды, контакты, компании, товары |
task | Задачи и проекты |
user | Пользователи портала |
disk | Файлы и папки Диска |
im | Мессенджер, чаты, уведомления |
department | Структура компании |
Принцип минимальных привилегий: запрашивайте только те scope, что реально нужны интеграции.
Права вебхука
Вебхук — простейший способ авторизации: это URL с секретным кодом, привязанный к конкретному пользователю. Права вебхука складываются из двух вещей:
- Выбранные scope при создании вебхука — какие разделы API он может дёргать.
- Права пользователя-владельца — вебхук действует с правами того сотрудника, что его создал.
Отсюда практическое следствие: если вебхук создал сотрудник с ограниченными правами в CRM, интеграция увидит только доступные ему сделки. Для полного доступа вебхук создают от имени администратора.
OAuth-приложения
Для тиражируемых решений и приложений Маркета используется OAuth 2.0. Здесь права выдаёт пользователь при установке приложения, подтверждая запрошенные scope.
Ключевые отличия от вебхука:
- Токен доступа (
access_token) временный и обновляется черезrefresh_token. - Права привязаны к пользователю, установившему приложение, и его роли на портале.
- Scope фиксируется в настройках приложения и подтверждается при установке.
Именно поэтому OAuth-приложения регулярно ловят expired_token — это штатная ситуация, требующая обновления токена, а не ошибка прав.
Права пользователя в CRM
Внутри модулей действует своя ролевая модель, и REST её полностью уважает. В CRM права настраиваются по ролям: чтение/изменение/удаление сделок «свои / отдела / все», доступ к воронкам и стадиям.
Практические последствия для интеграции:
- Списочный метод вернёт только те объекты, которые доступны пользователю запроса.
- Попытка изменить чужой объект без прав вернёт
ACCESS_DENIED. - Часть административных методов (настройки, роли, вебхуки) требует прав администратора портала.
Проверить доступность действий помогают методы вида *.userfield и служебные проверки прав конкретных модулей. Если данные «пропадают» в выборке — первым делом проверяйте права пользователя-владельца токена.
Ошибки доступа и их причины
| Ошибка | Причина | Что делать |
|---|---|---|
insufficient_scope | Метод вне разрешённых scope | Добавить scope в вебхук/приложение |
ACCESS_DENIED | Нет прав пользователя на объект | Проверить роль и права владельца токена |
ERROR_METHOD_NOT_FOUND | Метод недоступен в текущем scope | Проверить scope и имя метода |
INVALID_CREDENTIALS | Неверный код вебхука/приложения | Проверить учётные данные |
Диагностика идёт по цепочке: сначала проверяем scope методом scope, затем — права пользователя, от чьего имени работает токен.
Итог
Права в REST Битрикс24 проверяются дважды: на уровне scope приложения или вебхука и на уровне прав пользователя, в чьём контексте выполняется запрос. Ошибка insufficient_scope — про первое, ACCESS_DENIED — про второе. Соблюдайте принцип минимальных привилегий, берегите код вебхука и помните про истечение OAuth-токена.
Мы в B2Bsite настраиваем безопасные интеграции с Битрикс24: корректные scope, разграничение прав, защищённое хранение секретов и предсказуемая работа токенов. Если ваша интеграция то видит данные, то нет — поможем разобраться в правах и выстроить надёжную схему доступа.
Частые вопросы
Почему метод работает, но возвращает не все записи?
Запрос выполняется в контексте пользователя-владельца токена. Списочный метод вернёт только те объекты, на которые у этого пользователя есть права в модуле.
Что такое scope в REST Битрикс24?
Это набор разделов API (crm, task, user, disk и другие), к которым допущено приложение или вебхук. Проверить выданные права можно методом scope.
Чем права вебхука отличаются от OAuth-приложения?
Вебхук — статический секрет с правами создавшего его пользователя. OAuth выдаёт временный токен при установке приложения, обновляемый через refresh_token.
В чём разница между insufficient_scope и ACCESS_DENIED?
insufficient_scope — методу не выдан нужный scope. ACCESS_DENIED — у пользователя, от чьего имени идёт запрос, нет прав на конкретный объект или действие.
Как дать интеграции полный доступ к CRM?
Создать вебхук со scope crm от имени пользователя с правами на все сделки (обычно администратора), либо настроить соответствующую роль в правах CRM.
Можно ли публиковать код вебхука в клиентском коде?
Нет. Код в URL вебхука даёт доступ ко всем его scope. Храните его в защищённой серверной конфигурации и отзывайте при подозрении на утечку.
Почему OAuth-приложение постоянно ловит expired_token?
Это штатное поведение: access_token временный. Его нужно обновлять через refresh_token. Это вопрос жизненного цикла токена, а не ошибка прав доступа.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.