#Access mode

Every key has an accessMode field — it determines whether the key allows writes or restricts it to read operations. This setting is independent of scopes: scopes determine which data sections a key has access to, while the access mode determines 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 new keys, change the Bitrix24 account or send feedback, but can read settings and the event log.

#How to find out 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, six slots of the capabilities block — apps.create, apps.publish, apps.bindPlacements, servers.create, agents.create, managedBots.create — arrive with available: false and reason: "WRITE_BLOCKED_READONLY_KEY". Check that block before a request. It covers the six slots listed, not every endpoint: the two application exceptions are described above.

#Changing the mode

The key owner changes the mode in the dashboard in the API keys section:

1. Open the card of the needed key.
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 a valid key without replacing the value. When creating a new key, the mode is set by a separate toggle in the form.

The Bitrix24 account administrator sees others' keys in the shared list and can change the mode of any key on the Bitrix24 account. After saving, the owner gets a message from the Companion bot informing them that the mode of their key was changed by an administrator.

#Portal default policy

The administrator sets the mode that applies to all new keys on the Bitrix24 account. The setting lives in the API keys section in the "Portal default policy" block and is visible only to administrators.

Possible values:

• Read and write (READWRITE) — the default value for the Bitrix24 account. Any user creates keys with any 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, when needed, creates keys with write access or changes the mode of another user's key in the key's card.

The Bitrix24 account policy does not affect existing keys — it applies only at the moment of creating a new key. 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"
    }
  }
}

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 assigns an operation to read or write by its type. If the operation is unknown to it, it is treated as a write and blocked. A key in read-only mode will never let a write through because of a gap in the classifier.

The details.method field is not always present. It comes when a request addressed to the Bitrix24 account is blocked and contains the name of the operation that would have been performed. When a management key is blocked there is no field: there the decision is made by the request's HTTP method, 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

• Creating and using a key
• Key self-description
• Management keys
• Error codes