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

У каждого ключа есть поле `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`:

```bash
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"]
  }
}
```

Показана часть полей ответа. Полное описание — [Самоописание ключа](/docs/keys-auth/me).

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

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

Владелец ключа меняет режим в личном кабинете в разделе [Ключи API](/keys):

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

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

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

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

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

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

- **Чтение и запись (`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` | На портале действует политика «только чтение», а участник пытается выпустить ключ с записью |

Полный справочник кодов — [Коды ошибок](/docs/errors).

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

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

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

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

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

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

- [Создание и использование ключа](/docs/keys-auth)
- [Самоописание ключа](/docs/keys-auth/me)
- [Менеджмент-ключи](/docs/management-keys)
- [Коды ошибок](/docs/errors)