Scope и права доступа приложения

Scope — это набор областей прав, которые вебхук или приложение получает к модулям Битрикс24. От правильно подобранного scope зависит и безопасность, и работоспособность интеграции. Разберём, какие области бывают, как их проверять и почему нельзя выдавать «всё сразу».

Что такое scope

Scope (область действия) определяет, к каким модулям портала обращается ваша интеграция. Права выдаются на уровне модуля, а не отдельного метода: получив scope crm, приложение может вызывать все методы CRM (crm.deal.*, crm.lead.*, crm.contact.* и т. д.).

Scope задаётся один раз при создании вебхука или приложения. Внутри выданных прав интеграция всё равно ограничена правами пользователя: если у сотрудника нет доступа к чужим сделкам, приложение от его имени их тоже не увидит.

Основные области прав

Наиболее востребованные scope при интеграциях:

Полный актуальный список зависит от версии портала и его тарифа — свериться можно в документации и через метод scope.

Как проверить выданные права

Метод scope без параметров вернёт список прав, реально выданных вашей интеграции:

GET /rest/1/xxxx/scope.json

// Ответ
{ "result": ["crm", "user", "task"] }

Чтобы увидеть все возможные области портала, добавьте параметр full=true:

GET /rest/1/xxxx/scope.json?full=true

// Ответ — полный перечень доступных на портале областей

Метод methods покажет доступные вам методы, а method.get проверит доступность конкретного метода — удобно для диагностики перед вызовом.

Ошибка INSUFFICIENT_SCOPE

Самая частая ошибка прав выглядит так:

{
  "error": "INSUFFICIENT_SCOPE",
  "error_description": "The application does not have enough rights ..."
}

Она означает, что метод относится к модулю, права на который не выданы. Порядок разбора:

1. Определите модуль метода (например, telephony.externalcall.register → scope telephony).
2. Вызовите scope.json и проверьте, есть ли нужная область в списке.
3. Если нет — добавьте scope в настройках вебхука/приложения и переустановите приложение.

Принцип минимальных привилегий

Соблазн выдать «всё сразу» велик, но это плохая практика. Минимальный scope — это:

• Безопасность: при утечке токена или вебхука злоумышленник получит доступ только к разрешённому модулю, а не ко всему порталу.
• Доверие пользователей: на экране установки приложения виден список запрашиваемых прав — короткий список повышает конверсию.
• Прохождение модерации: тиражные приложения Маркетплейса с избыточными правами возвращают на доработку.
• Простота аудита: легче понять, что делает интеграция, по её правам.

Практическое правило: начинайте с одного-двух scope под конкретный сценарий и расширяйте по мере надобности, а не наоборот.

Scope не отменяет прав пользователя

Даже с выданным scope crm приложение видит ровно то, что видит пользователь, от чьего имени идёт вызов. Это важно понимать при отладке «пропавших» данных:

Поэтому для сервисных интеграций часто заводят отдельного пользователя с нужными правами и создают вебхук от его имени — так поведение предсказуемо и не зависит от увольнения конкретного сотрудника.

Итог

Scope — это контракт между вашей интеграцией и порталом: он определяет доступные модули, но не отменяет прав пользователя. Проверяйте выданные области методом scope, разбирайте INSUFFICIENT_SCOPE по модулю метода и придерживайтесь принципа минимальных привилегий. Это делает интеграцию безопаснее и понятнее.

Мы в B2Bsite проектируем модель доступа интеграций осознанно: минимальный необходимый scope, сервисные пользователи, разграничение прав и аудит — особенно важно на порталах с чувствительными данными клиентов.