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. ⚠️ There are a few exceptions: such a key can still deliver to the caller's own server — the set is under "Exceptions to the write block" below, the boundary caveat under "Known specifics". The set of PLATFORM exceptions also arrives in writeRestriction.exceptions in the GET /v1/me response; 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.

Exceptions to the write block

The set of exceptions lives in the platform code. This page prints it exactly as it arrives in the writeRestriction.exceptions field of the GET /v1/me response — each route is a pattern, with :id in place of a concrete identifier:

{
  "writeRestriction": {
    "restricted": "WRITE_BLOCKED_READONLY_KEY",
    "exceptions": [
      "DELETE /v1/connectors/mcp",
      "DELETE /v1/cowork/key",
      "DELETE /v1/infra/servers/:id/lock",
      "POST /v1/apps",
      "POST /v1/connectors/mcp",
      "POST /v1/infra/servers/:id/deploy",
      "POST /v1/infra/servers/:id/exec",
      "POST /v1/infra/servers/:id/icon",
      "POST /v1/infra/servers/:id/unstick",
      "POST /v1/infra/servers/:id/upload"
    ]
  }
}

These are addresses, not permissions: a route on the list runs its own check and may refuse for another reason. The groups it falls into:

• Delivery to a server the key already owns — the POST routes of the /v1/infra/servers/{id}/… family on the list above. A read-only key is allowed through them deliberately, by a policy decision rather than by oversight; for the owner of a server the mode is still not a boundary — see "Known specifics".
• Creating an application — POST /v1/apps. Such a key creates an application in READONLY mode; a request for READWRITE is refused.
• Two emergency exits that are not writes — revoking the key itself (DELETE /v1/cowork/key) and releasing a stuck lock (DELETE /v1/infra/servers/{id}/lock). The second releases the backend lock UNCONDITIONALLY and is therefore a second step, allowed only after the server has been independently confirmed idle; the recoveryAction field of an EXEC_BUSY response points not to it but to POST /v1/infra/servers/{id}/unstick.
• Connector gateway for the Cowork desktop — POST /v1/connectors/mcp and DELETE /v1/connectors/mcp (method not supported, answers 405). At stage 1A the gateway only lists and calls READ tools of connected services; a key can neither see nor call a write tool, in any mode.

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. For the full description, see 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 their account:

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 the changes — the mode takes effect from the next request.

No reissue is 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 on the Management Keys page, 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, command execution included. 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 for the Bitrix24 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 a deliberate trade-off. 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-only mode could not follow events.

Named chat reads with an employee’s personal key. An ordinary personal vibe_api_* key in READONLY mode can read an accessible existing chat. Vibecode checks the im scope; Bitrix24 checks the employee’s access. This is a narrow exception with known side effects of reading:

• Where the chat permits auto-join, a read may add the employee as a member.
• Presence updates are allowed only for im.v2.Chat.load, im.v2.Chat.loadInContext, im.v2.Chat.Message.tail, and im.v2.Chat.Message.getContext.
• Lazy project conversion is allowed only for im.v2.Chat.load and im.v2.Chat.loadInContext.
• After access checks, loading may update the temporary file-permission cache and extend the transport subscription to chat events. REST parameters cannot disable these effects.

The ignoreMark parameter selects the load position and does not mark messages as read. Explicit writes, including read marks, typing, membership changes, and im.v2.Chat.Message.list with read marking, remain blocked before the request reaches the Bitrix24 account. Implicit chat creation through an unconfirmed address is also blocked: numeric peers and me must be confirmed in the same employee’s recent dialogs, within 20 pages or 4,000 rows. Virtual guest authorization is outside this exception. See the exact addressing and read conditions in Access rights, Load chat, Messages, and Message context.

This exception for named reads applies only to an ordinary employee personal key, whether it uses a webhook or previously configured OAuth tokens. An application key with a user Bearer session, a management key, or a key whose owner kind is unconfirmed, in READONLY or PORTAL_READONLY mode, receives 403 WRITE_BLOCKED_READONLY_KEY before the existing-chat binding is checked and the named messenger method is called. Ordinary reads without these effects remain available to application keys; keys in read-write mode are unaffected.

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. The field is absent when the HTTP method guard blocks a management key. When a specific Bitrix24 operation is blocked, the field contains that operation’s name.

A key without a name is shown as unnamed. The details.keyName field shows the key name set in your account. 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 a Vibe+ plan restores full access; start the VM manually.