Rights to create keys and apps

Rights to create keys, apps and webhooks are set in two places — in the Vibecode dashboard and in Bitrix24. This page explains which setting lives where and how the text of a refusal tells you which one to change.

Two groups of settings

The checks run in sequence. Vibecode rights come first: if they deny the action, the refusal arrives before Bitrix24 is contacted. Bitrix24 rights come next, when a webhook is issued for the key.

Telling the two refusals apart

A Vibecode refusal only points you to your Bitrix24 account administrator and names no Bitrix24 right or setting. Creating a key, for example, returns "You don't have permission to create API keys. Contact your Bitrix24 account administrator." The codes are KEY_CREATION_RESTRICTED for a key and APP_CREATION_RESTRICTED for an app, both with status 403.

A Bitrix24 refusal names the right to create webhooks or to install apps. For example: "Your Bitrix24 account administrator hasn't granted you the right to create incoming webhooks. Ask them to open Settings → Security and either add you to the “Who can create incoming webhooks” field in the “Bitrix24 integrations” block, or turn on the “Permission source — Vibecode server” toggle in the “Vibecode Connector” block — then the rights are taken from the Vibecode dashboard." The codes are CONNECTOR_KEY_ISSUE_FORBIDDEN, CONNECTOR_APP_INSTALL_FORBIDDEN and B24_ACCESS_DENIED, all with status 403.

If the refusal came from Vibecode — codes KEY_CREATION_RESTRICTED and APP_CREATION_RESTRICTED — and you are not an administrator, send an access request from the dashboard. The administrator approves or declines it. The request is available when the setting uses list mode.

For the full list of codes, see Error codes.

Settings in the Vibecode dashboard

The section is available to the Bitrix24 account administrator.

1. Sign in to the Vibecode dashboard as a Bitrix24 account administrator.
2. Go to the Settings section.
3. Find the setting you need: the right to create keys is in the "Keys" card, the rest are in the "Creation Rules" card.
4. Choose a mode. In list mode, add the employees who are granted access.
5. Click "Save" in the same card.

Each setting has four modes: all users, administrators only, administrators and employees from a list, nobody. Keys and servers have a fifth one, "Inherit": they follow the rule set for apps, agents or bots.

In list mode, an employee who is not on the list can send an access request. The administrator approves or declines it.

The "Keys" card also sets the access mode for new keys — read-only, or read and write. It is saved the moment you switch it, needs no separate button, and does not affect keys already issued.

Settings in Bitrix24

The section is available to employees with Bitrix24 account administrator rights.

1. In Bitrix24, open the left menu, click "Settings" and choose "Bitrix24 settings".
2. In the list of sections on the left, choose "Security".
3. Expand the "Bitrix24 integrations" block.
4. In the field you need, click "+ Add" and choose employees.

The "Permission source — Vibecode server" toggle

It sits in the same place, on the Security tab, in the "Vibecode Connector" block. The toggle decides whether Bitrix24 applies its own lists when keys are issued and apps are installed through Vibecode.

1. Open Settings → Security in Bitrix24.
2. Expand the "Vibecode Connector" block.
3. Set the "Permission source — Vibecode server" toggle to the position you need.

Important: the toggle removes the check on the Bitrix24 side, but the rights set in the Vibecode dashboard apply in either position. If creation is restricted in the Vibecode dashboard, turning the toggle on will not grant access — the refusal arrives before the platform contacts Bitrix24.

The key exists, but calls do not go through

Rights restrict more than key creation. There are two cases where the key is issued and visible in the list, yet calls are rejected.

Calls to Bitrix24 answer `401 TOKEN_MISSING`

No webhook has been issued for the key. The reason is returned in the details.reason field:

{
  "success": false,
  "error": {
    "code": "TOKEN_MISSING",
    "message": "This key has no Bitrix24 webhook: the portal refused to create one for its owner. ...",
    "details": {
      "reason": "WEBHOOK_MINT_REFUSED_BY_PORTAL"
    }
  }
}

The value WEBHOOK_MINT_REFUSED_BY_PORTAL means that Bitrix24 denied the key owner the right to create incoming webhooks. Once the administrator grants that right, the platform issues the webhook within 15 minutes. There is no need to reconnect the key or issue a new one: a new key gets the same refusal.

The other details.reason values and what to do about each are in the TOKEN_MISSING section.

Modifying calls answer `403 WRITE_BLOCKED_READONLY_KEY`

The key was issued in read-only mode. The mode is set in the Vibecode dashboard, in the "Keys" card, at the moment the key is issued, and does not carry over to keys already issued. Such a key can read data but rejects modifying calls. An administrator can enable writes for an individual key from its card.

A personal READONLY key acting as a Bitrix24 employee can complete the chat reading flow through GET /v1/chats/{dialogId}/load, the v2 message feed, and GET /v1/chats/messages/{messageId}/context. These three read operations may conditionally run AutoJoinToChat: in a chat that allows it, the caller becomes a member. The exception names these methods; it does not apply to every call with a load, tail, or getContext suffix. Bitrix24 updates the employee's online presence on the named upstream reads Chat.load, Chat.loadInContext, Message.tail and Message.getContext. Chat.load and Chat.loadInContext can also trigger lazy project conversion through the external-chat loaded event. Chat.load grants quick file access only after checking chat access, may extend PullWatch for an open chat or Open Channel, and queues an external-chat loaded event; its collab or workgroup handler may trigger lazy project conversion. The REST method has no parameter to disable these effects. None of the three method bodies marks messages read: ignoreMark only chooses the load position. This description does not permit those effects on unrelated methods. The im scope, tokens, and the user's permissions in Bitrix24 are still checked. The dialog list and counters are also available to read. Explicit joins, read marks, and other state-changing commands get 403 WRITE_BLOCKED_READONLY_KEY before any call to Bitrix24. This describes employee authentication. Guest session authentication follows a separate Bitrix24 contract. Cowork routes retain their existing contract.

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 an employee Bearer session, a management key, or a key whose owner type is unconfirmed receives 403 WRITE_BLOCKED_READONLY_KEY in READONLY or PORTAL_READONLY before the existing-chat binding check and the call to the named messenger method. Ordinary reads without these effects remain available to application keys; read/write mode is unchanged.

READONLY reads an existing chat. For load, the message feed and the legacy dialog card, use chatN, where N identifies an existing chat. A numeric peer ID, including a resolved me, is accepted only after checking the same employee's recent dialogs for a private-dialog row with a positive chat_id. The check scans at most 20 pages of 200 raw rows and is shared by commands in one batch. If no existing chat is confirmed within that window, the API returns 403 WRITE_BLOCKED_READONLY_KEY and does not send Bitrix24 an alias that would create a dialog. This does not claim that the dialog is absent from the entire history. Project/CRM aliases and parameters that can create a comment chat are outside this exception. Context around a messageId uses an existing message. Bitrix24 access checks still apply; read/write mode keeps its existing parameter contract. Explicit read marks and typing remain writes.

The task form GET /v1/chats/{dialogId}/task-form and flow form GET /v1/chats/{dialogId}/flow-form remain blocked for READONLY: their conditional auto-join has no specific exception. GET /v1/chats/state marks the caller online, while GET /v1/chats/settings may persist a settings-preset binding. These distinct effects are writes and get 403 WRITE_BLOCKED_READONLY_KEY before any portal call.

Task chat feed. A read-only key reads the task chat feed in pages of at most 50 messages, whatever the limit: reading pages of up to 200 messages can make the employee a member of the chat, which changes Bitrix24 account data. Page through the history with the lastId cursor until hasNextPage: false. A key with write access reads up to 200 messages per page.

See also

• Keys and authorization
• Authorization, keys and permissions
• Create an application
• Quickstart