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

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

Два режима

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

• API-ключи и ключи авторизации (vibe_api_, vibe_app_) — блокируется любой запрос, который выполняет операцию записи: создание, обновление, удаление, действия над сущностями. Запросы чтения и агрегация (POST /v1/<entity>/aggregate) выполняются без ограничений, несмотря на метод POST.
• Менеджмент-ключи (vibe_live_) — блокировка идёт по HTTP-методу: POST, PATCH, PUT и DELETE отклоняются, GET и HEAD проходят. Это значит, что менеджмент-ключ в режиме «только чтение» не может создавать, изменять, перевыпускать и удалять ключи или отправлять обратную связь, но может читать настройки и журнал событий.

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

Действующий режим возвращает 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.deploy, servers.wake, agents.create, managedBots.create, aiRouter.chatCompletions, aiRouter.byok — приходят с available: false и reason: "WRITE_BLOCKED_READONLY_KEY". Слот apps.create в этом списке НЕ значится: таким ключом приложение в режиме READONLY создаётся (первое исключение выше), поэтому слот остаётся доступным, а запрет на режим READWRITE описан в его поле note. Сверяйтесь с этим блоком перед запросом. Он покрывает перечисленные слоты, а не каждый эндпоинт: два исключения по приложениям описаны выше.

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

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

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

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

Важно: раздел «Ключи API» показывает только личные ключи. Два других вида в нём не показываются по построению — ни у владельца, ни у администратора портала, — и режим у них переключается в другом месте: у ключа авторизации приложения (vibe_app_*) — в карточке приложения на странице «Приложения», у менеджмент-ключа (vibe_live_*) — в карточке ключа на странице «Менеджмент-ключи». Поле 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 to read+write in /keys to enable writes.",
    "details": {
      "method": "crm.item.add",
      "keyName": "Ключ интеграции",
      "currentMode": "READONLY",
      "switchUrl": "/keys"
    }
  }
}

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

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

Ошибки

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

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

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

Отметка «прочитано» — операция записи. Она меняет состояние портала: счётчик непрочитанного и статусы уведомлений. Поэтому 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 ключу «только чтение» доступны, хотя создают и снимают подписку: без них агент в режиме чтения не смог бы следить за событиями.

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

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

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

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

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