Для AI-агентов: markdown этой страницы — /docs-content/keys-auth/access-mode.md индекс документации — /llms.txt

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

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

Два режима

Режим Значение в API Что разрешено
Чтение и запись READWRITE Все операции — чтение и запись. Значение по умолчанию для новых ключей.
Только чтение READONLY Чтение разрешено. Запись возвращает 403 WRITE_BLOCKED_READONLY_KEY — кроме двух исключений в разделе «Приложения»: таким ключом можно создать приложение в режиме READONLY и изменить у приложения поля, не затрагивающие набор скоупов.

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

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

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

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

Terminal 
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.tech/v1/me
JSON 
{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "accessMode": "READONLY",
    "scopes": ["crm", "tasks"]
  }
}

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

Тот же ответ показывает последствия режима до вызова: у ключа в режиме «только чтение» шесть слотов блока capabilities — apps.create, apps.publish, apps.bindPlacements, servers.create, agents.create, managedBots.create — приходят с available: false и reason: "WRITE_BLOCKED_READONLY_KEY". Сверяйтесь с этим блоком перед запросом. Он покрывает перечисленные шесть слотов, а не каждый эндпоинт: два исключения по приложениям описаны выше.

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

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

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

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

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

Политика портала по умолчанию

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

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

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

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

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

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

JSON 
{
  "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"
    }
  }
}

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

Ошибки

HTTP Код Когда возвращается
403 WRITE_BLOCKED_READONLY_KEY У ключа режим READONLY, а вызов выполняет запись
403 KEY_POLICY_READONLY_REQUIRED На портале действует политика «только чтение», а участник пытается выпустить ключ с записью

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

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

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

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

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

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

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