Access mode

Every key has an accessMode field — it determines whether the key allows writes or is limited to read operations. This setting is independent of scopes: scopes determine which data sections a key has access to, while the access mode controls whether the key can change that data.

Two modes

What is blocked in read-only mode

• API keys and authorization keys (vibe_api_, vibe_app_) — any request that performs a write operation is blocked: create, update, delete, actions on entities. Read requests and aggregation (POST /v1/<entity>/aggregate) run without restrictions, despite the POST method.
• Management keys (vibe_live_) — blocking is by HTTP method: POST, PATCH, PUT and DELETE are rejected, GET and HEAD pass. This means a management key in read-only mode cannot create, change, rotate or delete keys, or send feedback, but can read settings and the event log.

How to check a key's mode

The mode in effect is returned by GET /v1/me in the data.accessMode field:

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

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

Only some of the response fields are shown. Full description — Key self-description.

The same response shows the consequences of the mode before you make a call: for a key in read-only mode, nine slots in the capabilities block — apps.publish, apps.bindPlacements, servers.create, servers.deploy, servers.wake, agents.create, managedBots.create, aiRouter.chatCompletions, aiRouter.byok — arrive with available: false and reason: "WRITE_BLOCKED_READONLY_KEY". apps.create is NOT on that list: such a key does create an application in READONLY mode (the first exception above), so the slot stays available and the ban on READWRITE is spelled out in its note field. Check that block before making a request. It covers the slots listed, not every endpoint: the two application exceptions are described above.

Changing the mode

The owner of a personal key changes the mode in the API Keys section of the dashboard:

1. Open the card of the key you want to change.
2. In the Access mode block, choose "Read only" or "Read and write".
3. Save changes — the mode applies to the next request.

Reissue is not needed — the mode changes on an existing key without replacing its value. When creating a new key, the mode is set by a separate toggle in the form.

Important: the API Keys section lists personal keys only. The two other kinds are never listed there, by construction — neither for the owner nor for the Bitrix24 account administrator — and their mode is switched elsewhere: an application auth key (vibe_app_*) on the application card on the Applications page, a management key (vibe_live_*) on the key's card on the Management Keys page. The switchUrl field of the refusal always points at the page that carries the switch for that particular key.

The Bitrix24 account administrator sees other users' keys in the shared list and can change the mode of any key in that list — that is, of the same personal keys: application auth keys are not listed there (see the box above), and the administrator switches their mode in the same place, on the application card. After saving, the owner gets a message from the Companion bot informing them that the mode of their key was changed by an administrator.

Bitrix24 account policy

The administrator sets the mode that applies to all new keys on the Bitrix24 account. The "Access mode for new keys" toggle is visible only to administrators — it lives in the Settings section, the "Keys" card.

Possible values:

• Read and write (READWRITE) — the default value for the Bitrix24 account. Any user can create keys in either mode at their discretion.
• Read-only (READONLY) — regular Bitrix24 account members can create only read-only keys. An attempt to issue a key with READWRITE mode is rejected with code 403 KEY_POLICY_READONLY_REQUIRED. The Bitrix24 account administrator is not subject to this restriction and can, when needed, create keys with write access or change the mode of another user's key in that key's card.

The Bitrix24 account policy does not affect existing keys — it applies only when a new key is created. For already issued keys, the administrator changes the mode manually in the key card.

Response example when a write is blocked

POST /v1/leads with a key in READONLY mode returns 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": "Integration key",
      "currentMode": "READONLY",
      "switchUrl": "/keys"
    }
  }
}

Important: switchUrl is not a constant. The example above is a personal key, so the path points at the keys page. The other kinds are never listed on /keys by construction, and their paths differ: an application auth key (vibe_app_*) points at the Applications page — /applications, a management key (vibe_live_*) at /management-keys. Read the value from the response instead of hardcoding one.

The request is rejected before reaching the Bitrix24 account, so the write is not performed even partially.

Errors

The full code reference — Error codes.

Known specifics

An unknown operation is treated as a write. The classifier decides whether an operation is a read or a write by its type. If the operation is unknown to it, it is treated as a write and blocked. A gap in the classifier can never make a key in read-only mode let a write through.

Marking something as read is a write operation. It changes state on the Bitrix24 account: the unread counter and notification statuses. That is why POST /v1/notifications/read, POST /v1/chats/:dialogId/read and POST /v1/bots/:botId/chats/:dialogId/read return 403 WRITE_BLOCKED_READONLY_KEY when called with a read-only key. Reading notifications and messages with such a key still works.

Subscribing to chat events is a deliberate exception. POST /v1/chats/events/subscribe and POST /v1/chats/events/unsubscribe are available to a read-only key even though they create and remove a subscription: without them an agent in read mode could not follow events.

The details.method field is not always present. It arrives when a request addressed to the Bitrix24 account is blocked, and it carries the name of the operation that would have been performed. When a management key is blocked, the field is absent: in that case the decision is made by the HTTP method of the request, not by the operation.

A key without a name is shown as unnamed. The details.keyName field shows the key name from the dashboard. If the name is empty, the response returns unnamed.

The message comes in English. The error.message field is not localized — the block triggers at a point where the user's language is not yet determined. Interfaces localize the message by the error.code value.

See also

• Keys and authorization
• Key self-description
• Management keys
• Errors