Режим доступа

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

Два режима

Что блокируется в режиме «только чтение»

• API-ключи и ключи авторизации (vibe_api_, vibe_app_) — блокируется ЛЮБОЙ запрос записи, кроме перечня исключений: и запись данных Битрикс24 (создание, обновление, удаление, действия над сущностями), и платформенная запись — создание сервера, пробуждение, расписания пробуждения, создание агентов и ботов, публикация приложения, места встраивания, вызовы ИИ-роутера. Важно: исключения есть, и их немного: доставка на собственный сервер вызывающего таким ключом проходит — состав в разделе «Исключения из запрета записи» ниже, оговорка про границу в «Известных особенностях». Перечень ПЛАТФОРМЕННЫХ исключений приходит и в writeRestriction.exceptions ответа GET /v1/me. Исключения на операциях, делегированных в Битрикс24, в это поле не попадают и описаны ниже, в «Известных особенностях». Запросы чтения и агрегация (POST /v1/<entity>/aggregate) выполняются без ограничений, несмотря на метод POST. Чтение базы приложения — POST /v1/infra/servers/:id/db/query. Это исключение работает и для менеджмент-ключей: SQL выполняется только на чтение. Маршруты базы закрыты флагом app-db, выключенным по умолчанию. Примеры проверены на локальной SQLite-фикстуре, без запроса к боевому серверу.

• Менеджмент-ключи (vibe_live_) — блокировка идёт по HTTP-методу: POST, PATCH, PUT и DELETE отклоняются, кроме описанного выше запроса к базе только на чтение; GET и HEAD проходят. Это значит, что менеджмент-ключ в режиме «только чтение» не может создавать, изменять, перевыпускать и удалять ключи или отправлять обратную связь, но может читать настройки и журнал событий.

Исключения из запрета записи

Состав исключений живёт в коде платформы. Эта страница печатает его ровно в том виде, в каком он приходит в поле writeRestriction.exceptions ответа GET /v1/me — маршрут записан шаблоном, с :id вместо конкретного идентификатора:

{
  "writeRestriction": {
    "restricted": "WRITE_BLOCKED_READONLY_KEY",
    "exceptions": [
      "DELETE /v1/connectors/mcp",
      "DELETE /v1/cowork/key",
      "DELETE /v1/infra/servers/:id/lock",
      "POST /v1/apps",
      "POST /v1/connectors/mcp",
      "POST /v1/infra/servers/:id/db/query",
      "POST /v1/infra/servers/:id/deploy",
      "POST /v1/infra/servers/:id/exec",
      "POST /v1/infra/servers/:id/icon",
      "POST /v1/infra/servers/:id/unstick",
      "POST /v1/infra/servers/:id/upload"
    ]
  }
}

Это адреса, а не разрешения: маршрут из списка выполняет собственную проверку и может отказать по другой причине. Группы, на которые он делится:

• Доставка на уже свой сервер — POST-маршруты семейства /v1/infra/servers/{id}/… из списка выше. Ключу «только чтение» они разрешены осознанно, решением о политике, а не по недосмотру; границей владельцу сервера режим при этом не является — см. «Известные особенности».
• Создание приложения — POST /v1/apps. Таким ключом создаётся приложение в режиме READONLY; запрос режима READWRITE отклоняется.
• Два аварийных выхода, записью не являющиеся — отзыв собственного ключа (DELETE /v1/cowork/key) и снятие залипшего лока (DELETE /v1/infra/servers/{id}/lock). Второй снимает backend-лок БЕЗУСЛОВНО и потому является вторым шагом, допустимым лишь после независимо подтверждённого простоя сервера; поле recoveryAction ответа EXEC_BUSY указывает не на него, а на POST /v1/infra/servers/{id}/unstick.
• Шлюз коннекторов десктопа Коворк — POST /v1/connectors/mcp и DELETE /v1/connectors/mcp (метод не поддержан, отвечает 405). На этапе 1A шлюз выставляет и вызывает только читающие инструменты подключённых сервисов; пишущий инструмент ключ не увидит и не сможет вызвать ни в каком режиме.

Как узнать режим ключа

Действующий режим возвращает GET /v1/me в поле data.accessMode:

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/me

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "accessMode": "READONLY",
    "scopes": ["crm", "tasks"]
  }
}

Показана часть полей ответа. Полное описание — Самоописание ключа.

Тот же ответ показывает последствия режима до вызова: у ключа в режиме «только чтение» слоты блока capabilities apps.publish, apps.bindPlacements, servers.create, servers.wake, agents.create, managedBots.create, aiRouter.chatCompletions и aiRouter.byok приходят с available: false и reason: "WRITE_BLOCKED_READONLY_KEY". Два слота в этом списке НЕ значатся. apps.create — таким ключом приложение в режиме READONLY создаётся, поэтому слот остаётся доступным, а запрет на режим READWRITE описан в его поле note. servers.deploy — доставка на уже свой сервер такому ключу разрешена. Сверяйтесь с этим блоком перед запросом: он покрывает перечисленные слоты, а не каждый эндпоинт.

Изменение режима

Владелец личного ключа меняет режим в личном кабинете в разделе Ключи API:

1. Откройте карточку нужного ключа.
2. В блоке Режим доступа выберите «Только чтение» или «Чтение и запись».
3. Сохраните изменения — режим применяется к следующему запросу.

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

Важно: раздел «Ключи API» показывает только личные ключи. Два других вида в нём не показываются по построению — ни у владельца, ни у администратора портала, — и режим у них переключается в другом месте: у менеджмент-ключа (vibe_live_*) — в карточке ключа на странице «Менеджмент-ключи», у ключа авторизации приложения (vibe_app_*) — в карточке приложения, которая живёт на одной из ДВУХ страниц. Если приложение заведено в разделе «Приложения» — карточка там (/applications). Если нет — на странице «Ключи авторизации» (/apps), где карточка открывается из меню строки, пункт «Информация»; блок Режим доступа стоит там сразу под ключом. Поле switchUrl в ответе об отказе всегда ведёт туда, где переключатель есть именно для этого ключа, — читайте его, а не выбирайте страницу на глаз.

Администратор портала видит чужие ключи в общем списке и может изменить режим любого ключа из этого списка — то есть тех же личных ключей: ключи авторизации приложений в нём не показываются (врезка выше), и их режим администратор переключает там же, в карточке приложения — на любой из двух её страниц. После сохранения владелец получает сообщение от Companion-бота с информацией о том, что режим его ключа был изменён администратором.

Политика портала

Администратор задаёт режим, который применяется ко всем новым ключам портала. Переключатель «Режим доступа для новых ключей» видят только администраторы — он живёт в разделе Настройки, карточка «Ключи».

Возможные значения:

• Чтение и запись (READWRITE) — значение по умолчанию для портала. Любой пользователь создаёт ключи с любым режимом на своё усмотрение.
• Только чтение (READONLY) — обычные участники портала могут создавать только ключи с режимом «только чтение». Попытка выпустить ключ с режимом READWRITE отклоняется с кодом 403 KEY_POLICY_READONLY_REQUIRED. Администратор портала под это ограничение не подпадает и при необходимости создаёт ключи с записью или меняет режим чужого ключа в его карточке.

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

Пример ответа при блокировке записи

POST /v1/leads с ключом в режиме READONLY возвращает 403:

{
  "success": false,
  "error": {
    "code": "WRITE_BLOCKED_READONLY_KEY",
    "message": "Key is in read-only mode. Switch the key to read and write in /keys to allow Bitrix24 data changes.",
    "details": {
      "method": "crm.item.add",
      "keyName": "Ключ интеграции",
      "currentMode": "READONLY",
      "switchUrl": "/keys"
    }
  }
}

Важно: switchUrl — не константа. В примере выше личный ключ, поэтому путь ведёт на страницу ключей. Остальные виды на /keys не показываются по построению, и путь у них другой: у менеджмент-ключа (vibe_live_*) — /management-keys, у ключа авторизации приложения (vibe_app_*) — /applications или /apps, смотря где живёт карточка этого приложения (врезка выше). Читайте значение из ответа, а не подставляйте своё.

Запрос отклоняется до обращения к порталу, поэтому запись не выполняется даже частично.

Поле portalWriteRestriction

У ключа в режиме «только чтение» в корне ответа GET /v1/me приходит поле portalWriteRestriction — второе заявление о запрете, рядом с writeRestriction. Поля разводят две стороны запрета:

• writeRestriction — платформенные записи: серверы, хранилище, обращения, ключи. Поле исчезает, если платформенный админ снимает этот запрет аварийным рычагом.
• portalWriteRestriction — изменение данных Битрикс24. От этого рычага не зависит: делегированные записи в Битрикс24 отказывают и при снятом платформенном запрете.

Маршруты в routes условные: запись называет не «этот маршрут закрыт», а условие отказа. Например, PATCH /v1/apps/:id отказывает на приложении, созданном не этим ключом, но пропускает правку описания своего приложения. Удаление сервера отказывает, только если на сервере работает ИИ-агент. Группы — apps, placements, feedback, relink-oauth, server-access и agent-cascade. Состав читайте из ответа: список строится из того же реестра, по которому решает сервер.

Фрагмент ответа:

"portalWriteRestriction": {
  "restricted": "WRITE_BLOCKED_READONLY_KEY",
  "appliesTo": "changes to Bitrix24 data through this API: delegated calls (decided by the per-method classifier) and the routes listed in `routes`",
  "routes": [
    {
      "name": "relink-oauth",
      "routes": ["POST /v1/apps/:id/relink-oauth"],
      "condition": "Always refused."
    }
  ],
  "note": "This key cannot change Bitrix24 data. …",
  "docs": "https://vibecode.bitrix24.tech/docs/keys-auth/access-mode"
}

Ошибки

Полный справочник кодов — Коды ошибок.

Известные особенности

Владельцу сервера режим «только чтение» границей НЕ является. Ключу с таким режимом разрешена доставка на собственный сервер, включая выполнение команд в нём. Выложенный код исполняется в контейнере, а там лежат креденшлы, которые платформа выдала приложению: персональный API-ключ приложения (он в режиме «чтение и запись») и токены приложения к порталу. Прочитав окружение, держатель ключа «только чтение» получает право писать данные Битрикс24. Сама ручка данные портала не пишет — но даёт доступ к тем, кто пишет, и это осознанная цена решения. Единственный надёжный рычаг, если такой доступ давать не хотят, — отозвать ключ. Выдавать ключ в режиме «только чтение» ради ограничения доставки бессмысленно.

Незнакомая операция считается записью. Классификатор относит операцию к чтению или записи по её типу. Если операция ему неизвестна, она трактуется как запись и блокируется. Ключ в режиме «только чтение» никогда не пропустит запись из-за пробела в классификаторе.

Отметка «прочитано» — операция записи. Она меняет состояние портала: счётчик непрочитанного и статусы уведомлений. Поэтому POST /v1/notifications/read, POST /v1/chats/:dialogId/read и POST /v1/bots/:botId/chats/:dialogId/read под ключом «только чтение» отвечают 403 WRITE_BLOCKED_READONLY_KEY. Само чтение уведомлений и сообщений таким ключом доступно.

Подписка на события чатов — осознанное исключение. POST /v1/chats/events/subscribe и POST /v1/chats/events/unsubscribe ключу «только чтение» доступны, хотя создают и снимают подписку: без них агент в режиме чтения не смог бы следить за событиями.

Именованные чтения чатов личным ключом сотрудника. Обычный личный ключ vibe_api_* в режиме READONLY может читать доступный существующий чат. Vibe проверяет скоуп im, Битрикс24 — доступ сотрудника. Это узкое исключение с известными эффектами чтения:

• При разрешённом в чате автовступлении чтение может добавить сотрудника в участники.
• Обновление присутствия допускается только для im.v2.Chat.load, im.v2.Chat.loadInContext, im.v2.Chat.Message.tail и im.v2.Chat.Message.getContext.
• Ленивое преобразование проекта допускается только при im.v2.Chat.load и im.v2.Chat.loadInContext.
• После проверки доступа загрузка может обновить временный кеш разрешений на файлы и продлить подписку транспорта на события чата. REST-параметров отключения перечисленных эффектов нет.

Параметр ignoreMark выбирает позицию загрузки и не отмечает сообщения прочитанными. Явные команды записи, включая отметки прочтения, typing, изменение членства и im.v2.Chat.Message.list с отметкой прочтения, остаются закрытыми до обращения к порталу. Неявное создание чата через неподтверждённый адрес также закрыто: числовой собеседник и me должны быть подтверждены в последних диалогах того же сотрудника, в пределах 20 страниц или 4 000 строк. Авторизация виртуального гостя не входит в это исключение. Точные условия адресации и чтений — Права доступа, Загрузка чата, Чтение сообщений и Сообщения вокруг сообщения.

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

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

Ключ без названия отображается как unnamed. Поле details.keyName показывает название ключа из личного кабинета. Если название пустое, в ответе приходит unnamed.

Сообщение приходит на английском языке. Поле error.message не локализуется — блокировка срабатывает в точке, где язык пользователя ещё не определён. Интерфейсы переводят по коду error.code.

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

• Ключи и авторизация
• Самоописание ключа
• Менеджмент-ключи
• Коды ошибок