Права на создание ключей и приложений

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

Две группы настроек

Проверки идут по очереди. Сначала права Вайбкод: если они закрыты, отказ приходит до обращения к Битрикс24. Затем, при выпуске вебхука для ключа, права Битрикс24.

Как понять, кто отказал

Отказ Вайбкод называет администратора портала и не упоминает Битрикс24. Например, при создании ключа приходит текст «У вас нет прав на создание API-ключей. Обратитесь к администратору портала.» Коды — KEY_CREATION_RESTRICTED для ключа и APP_CREATION_RESTRICTED для приложения, оба со статусом 403.

Отказ Битрикс24 прямо называет право на вебхуки или на установку приложений. Например: «Администратор портала Битрикс24 не выдал вам право создавать входящие вебхуки. Попросите его открыть «Настройки» → «Безопасность» и либо добавить вас в поле «Кому разрешить создавать входящие вебхуки» в блоке «Интеграции Битрикс24», либо включить переключатель «Источник прав — Вайбкод-сервер» в блоке «Вайбкод-коннектор» — тогда права берутся из кабинета Вайбкод.» Коды — CONNECTOR_KEY_ISSUE_FORBIDDEN, CONNECTOR_APP_INSTALL_FORBIDDEN и B24_ACCESS_DENIED, все со статусом 403.

Если отказ пришёл от Вайбкод — коды KEY_CREATION_RESTRICTED и APP_CREATION_RESTRICTED — и вы не администратор, отправьте заявку на доступ из кабинета. Администратор одобрит или отклонит её. Заявка доступна, когда для настройки выбран режим со списком.

Полный список кодов — Ошибки.

Настройки в кабинете Вайбкод

Раздел доступен администратору Битрикс24.

1. Откройте кабинет Вайбкод под учётной записью администратора Битрикс24.
2. Перейдите в раздел «Настройки».
3. Найдите нужную настройку: право создавать ключи находится в карточке «Ключи», остальные — в карточке «Правила создания».
4. Выберите режим. В режиме со списком добавьте сотрудников, которым доступ открыт.
5. Нажмите «Сохранить» в той же карточке.

У каждой настройки четыре режима: все пользователи, только администраторы, администраторы и сотрудники из списка, никто. У ключей и серверов есть пятый — «Наследовать»: действует то же правило, что задано для приложений, агентов или ботов.

В режиме со списком сотрудник, которого в списке нет, может отправить заявку на доступ. Администратор одобряет или отклоняет её.

В карточке «Ключи» задаётся режим доступа для новых ключей — только чтение или чтение и запись. Он сохраняется сразу при переключении, отдельной кнопки не требует, и на уже выпущенные ключи не влияет.

Настройки в Битрикс24

Раздел доступен сотрудникам с правами администратора Битрикс24.

1. В Битрикс24 откройте левое меню, нажмите «Настройки» и выберите «Настройки Битрикс24».
2. В списке разделов слева выберите «Безопасность».
3. Разверните блок «Интеграции Битрикс24».
4. В нужном поле нажмите «+ Добавить» и выберите сотрудников.

Переключатель «Источник прав — Вайбкод-сервер»

Находится там же, на вкладке «Безопасность», в блоке «Вайбкод-коннектор». Переключатель решает, применяет ли Битрикс24 свои списки при выпуске ключей и установке приложений через Вайбкод.

1. Откройте «Настройки» → «Безопасность» в Битрикс24.
2. Разверните блок «Вайбкод-коннектор».
3. Установите переключатель «Источник прав — Вайбкод-сервер» в нужное положение.

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

Ключ создан, но вызовы не проходят

Права закрывают не только создание ключа. Два случая, когда ключ выпущен и виден в списке, а вызовы отклоняются.

Вызовы к Битрикс24 отвечают `401 TOKEN_MISSING`

Вебхук для ключа не выписан. Причина приходит в поле details.reason:

{
  "success": false,
  "error": {
    "code": "TOKEN_MISSING",
    "message": "This key has no Bitrix24 webhook: the portal refused to create one for its owner. ...",
    "details": {
      "reason": "WEBHOOK_MINT_REFUSED_BY_PORTAL"
    }
  }
}

Значение WEBHOOK_MINT_REFUSED_BY_PORTAL означает, что Битрикс24 отказал владельцу ключа в праве создавать входящие вебхуки. Эту причину получает только ключ Коворка: он выдаётся при входе в приложение и тогда, когда вебхук выпустить не удалось. Другие ключи её не получают — личный ключ, например, при таком отказе не создаётся вовсе, и выпуск в кабинете отвечает 403 CONNECTOR_KEY_ISSUE_FORBIDDEN.

Администратор открывает право на входящие вебхуки, и после этого платформа выпускает вебхук ключу Коворка сама. Попытка повторяется не реже раза в сутки, поэтому доступ появляется в течение суток. Чтобы доступ появился сразу, сотрудник выходит из Коворка и входит снова — при входе ключ выпускается заново, уже с вебхуком. Пока право закрыто, повторный вход не помогает: новый ключ получит тот же отказ.

Остальные значения details.reason и порядок действий по каждому — в разделе TOKEN_MISSING.

Изменяющие вызовы отвечают `403 WRITE_BLOCKED_READONLY_KEY`

Ключ выпущен в режиме только чтения. Режим задаётся в кабинете Вайбкод на момент выпуска, в карточке «Ключи», и на уже выпущенные ключи не переносится. Такой ключ выполняет чтения и отклоняет изменяющие вызовы. Администратор может открыть запись отдельному ключу в его карточке.

Для полного сценария чтения чата личный ключ READONLY, действующий от имени сотрудника Битрикс24, может вызвать GET /v1/chats/{dialogId}/load, ленту в режиме v2 и GET /v1/chats/messages/{messageId}/context. Эти три операции чтения могут условно выполнить AutoJoinToChat: в чате, где разрешено автовступление, пользователь становится участником. Исключение относится к названным методам, а не ко всем вызовам с суффиксом load, tail или getContext. Битрикс24 обновляет присутствие сотрудника на именованных чтениях Chat.load, Chat.loadInContext, Message.tail и Message.getContext. Chat.load и Chat.loadInContext также могут запустить ленивое преобразование проекта через событие загрузки внешнего чата. При Chat.load Б24 выдаёт быстрый доступ к файлам только после проверки доступа к чату, может продлить PullWatch открытого чата или открытой линии и ставит фоновое событие загрузки внешнего чата. Для коллаба или рабочей группы его обработчик может запустить ленивое преобразование проекта. Параметров отключения этих эффектов у REST-метода нет. Тела трёх методов не ставят отметку прочтения: ignoreMark только выбирает точку загрузки. Исключение не распространяет обновление присутствия и преобразование проекта на другие методы. Проверки скоупа im, токенов и прав пользователя в Б24 сохраняются. Список диалогов и счётчики также доступны для чтения. Явное вступление, отметка прочтения и другие команды изменения получают 403 WRITE_BLOCKED_READONLY_KEY до обращения к порталу. Это описание относится к авторизации сотрудника. Авторизация гостевой сессии следует отдельному контракту портала. Маршруты Коворка работают по своему существующему контракту.

Тому же ключу доступны и другие чтения существующего чата, которые тоже могут сделать пользователя участником, если чат разрешает автовступление:

• Информация о диалоге в режиме format=v2
• Загрузка чата с shallow=true
• Загрузка вокруг сообщения
• Проверка доступа к чату или сообщению
• Список участников в режиме format=v2
• Состав чата по сущностям
• Активные участники
• Записи участия
• Проверка участия
• Кого можно упомянуть
• Список закреплённых сообщений
• Число закреплённых сообщений
• Поиск сообщений в чате
• Список реакций на сообщение

Исключение для этих именованных чтений действует только для обычного личного ключа сотрудника — как с вебхуком, так и с ранее настроенными OAuth-токенами. Ключ приложения с пользовательской Bearer-сессией, менеджмент-ключ и ключ с неподтверждённым видом владельца в режиме READONLY получают 403 WRITE_BLOCKED_READONLY_KEY до проверки привязки существующего чата и вызова именованного метода мессенджера. Обычные чтения без этих эффектов остаются доступны ключам приложений. Режим с записью не меняется.

READONLY читает существующий чат. Для чтений выше, которые принимают dialogId, а также для ленты и карточки диалога в любом режиме можно передать chatN, где N — ID уже существующего чата. Числовой ID собеседника, в том числе результат разрешения me, принимается только после проверки списка последних диалогов того же сотрудника: нужна строка личного диалога с положительным chat_id. Проверка ограничена 20 страницами по 200 исходных строк и разделяется между командами одного batch. Если существующий чат не подтверждён в этом окне, API отвечает 403 WRITE_BLOCKED_READONLY_KEY и не отправляет вызывающий создание алиас на портал. Это не утверждение, что диалога нет во всей истории. Алиасы проекта/CRM и параметры, способные создать чат комментариев, этим исключением не разрешены. Чтение вокруг messageId использует существующее сообщение. Обычные проверки доступа Б24 сохраняются. Режим с записью продолжает принимать свои прежние параметры. Явные отметки прочтения и typing остаются изменяющими вызовами.

Формы задачи GET /v1/chats/{dialogId}/task-form и потока GET /v1/chats/{dialogId}/flow-form остаются закрыты для READONLY: их условное автовступление не включено в точечное исключение. GET /v1/chats/state отмечает пользователя «в сети», а GET /v1/chats/settings может сохранить привязку к набору настроек. Эти отдельные эффекты считаются записью и получают 403 WRITE_BLOCKED_READONLY_KEY до обращения к порталу.

Лента чата задачи. Ключ только для чтения читает ленту чата задачи страницей не больше 50 сообщений при любом limit: чтение страницей до 200 сообщений может сделать сотрудника участником чата, то есть изменить данные портала. Листайте историю курсором lastId до hasNextPage: false. До 200 сообщений на страницу читает ключ с правом записи.

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

• Ключи и авторизация
• Авторизация, ключи и права
• Создать приложение
• Быстрый старт