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 write request is blocked except the listed exceptions: both writes of Bitrix24 data (create, update, delete, actions on entities) and platform writes — creating a server, waking it, wake schedules, creating agents and bots, publishing an application, placements, AI router calls. ⚠️ The exceptions exist and are few: delivery to the caller's own server (deploy, command execution, file upload, the icon, releasing a stuck exec lock) does pass for such a key — see the table above and the boundary caveat under "Known specifics". Read the set of PLATFORM exceptions from writeRestriction.exceptions in the GET /v1/me response, not from here; exceptions on operations delegated to Bitrix24 do not appear in that field and are described under "Known specifics" below. 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 the capabilities slots apps.publish, apps.bindPlacements, servers.create, servers.wake, agents.create, managedBots.create, aiRouter.chatCompletions and aiRouter.byok arrive with available: false and reason: "WRITE_BLOCKED_READONLY_KEY". Two slots are NOT on that list. apps.create — such a key does create an application in READONLY mode, so the slot stays available and the restriction on READWRITE mode is spelled out in its note field. servers.deploy — delivery to a server the key already owns is allowed for such a key. Check that block before making a request: it covers the slots listed, not every endpoint.

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: a management key (vibe_live_*) on the key's card in the Management keys section, an application auth key (vibe_app_*) on the application card — which lives on one of TWO pages. If the application is registered in the Applications section, its card is there (/applications). If it is not, the card is on the Auth Keys page (/apps), opened from the row menu, item "Info"; the Access mode block sits right under the key there. The switchUrl field of the refusal always points at the page that carries the switch for that particular key — read it instead of picking a page by eye.

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 — on whichever of its two pages it lives. 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: a management key (vibe_live_*) points at /management-keys, and an application auth key (vibe_app_*) at either /applications or /apps, depending on where that application's card lives (see the box above). 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

⚠️ For the owner of a server, read-only mode is NOT a boundary. A key in that mode is allowed to deliver code to its own server — deployment, command execution, file upload. The deployed code runs inside the container, and the credentials the platform issued to that application live there: the application's personal API key (which is in read+write mode) and the application's tokens to the account. By reading the environment, the holder of a read-only key obtains the right to write Bitrix24 data. The endpoint itself writes no account data — but it grants access to credentials that do, and that is an accepted price of the decision. The only reliable lever, when such access is not wanted, is to revoke the key; issuing a read-only key in order to restrict delivery achieves nothing.

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 let a write slip past a key in read-only mode.

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 is returned 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

On .com, an active Vibe+ trial grants agent and managed-bot access with a shared one-VM limit. After expiry, creating and starting are rejected and the demo VM is frozen asynchronously; its agent or bot is retained and stays viewable, stoppable and deletable. The trial excludes Galaxy and paid AI usage beyond the included quota. Buying Vibe+ restores full access; start the VM manually.