Bot access recovery

A bot is bound to the key it was registered with, so another key does not see it in the list and cannot claim the same code. Access is restored by transferring ownership to a working key — the bot is not re-created, chats and message history are preserved.

What a loss of access looks like

The symptoms appear all at once:

• GET /v1/bots returns success and an empty bots array, even though the bot is running on the Bitrix24 account.
• POST /v1/bots with the same code returns 409 BOT_ALREADY_EXISTS — the code is taken.
• GET /v1/bots/:botId with the identifier from the 409 response returns 403 BOT_ACCESS_DENIED.
• At the same time, GET /v1/me confirms that the key itself is valid: accessMode equals READWRITE, the imbot scope is present.

The bot list returned to a key that does not manage those bots:

{
  "success": true,
  "data": {
    "bots": [],
    "users": [],
    "hasNextPage": false
  }
}

Repeated registration with the same code — the existing bot is returned in the data field:

{
  "success": false,
  "error": {
    "code": "BOT_ALREADY_EXISTS",
    "message": "Bot with this code already exists"
  },
  "data": {
    "botId": 42,
    "code": "support_bot",
    "name": "Support"
  }
}

A request to this bot with the same key:

{
  "success": false,
  "error": {
    "code": "BOT_ACCESS_DENIED",
    "message": "This bot belongs to a different API key"
  }
}

Why the bot is not visible

A bot has two different bindings. Ownership is assigned to a Vibecode user and does not change when keys expire or are revoked. The binding to a key means something else — which key manages the bot right now.

GET /v1/bots returns records from the Vibecode database filtered by the calling key, so a bot registered with another key does not appear in the list. The other operations — events, messages and updates — are authorized the same way and return 403 BOT_ACCESS_DENIED.

Bot code uniqueness is checked within the Bitrix24 account, not the key. Hence the discrepancy: the list is empty, and the code is taken.

The bot itself is not affected. It stays on the Bitrix24 account, remains in the same chats and keeps its message history — only managing it through the API is unavailable.

How to restore access

Four steps. Calls to the bot are made with the key that ownership is transferred to. The transfer is available to the bot owner, that is, the Vibecode user who owns the owner key. A Bitrix24 account administrator can also perform the transfer.

1. Get the bot identifier

Repeat the registration with the same code. A 409 response means the code is taken: the identifier of the existing bot is returned in data.botId, and the bot record does not change. Registration is performed on behalf of a Bitrix24 account administrator — otherwise Bitrix24 denies access.

curl -X POST https://vibecode.bitrix24.com/v1/bots \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "support_bot", "name": "Support" }'

A 201 response instead of 409 means the registration went through idempotently. Ownership does not transfer in that case, the bot still does not appear in GET /v1/bots, and its name, type, eventMode and webhookUrl are updated with the values from the request. If the bot was working in webhook mode, send eventMode and webhookUrl together with code and name to preserve event delivery. The bot identifier in this response is returned in data.botId — go to step 2.

The procedure applies to bots registered through Vibecode. A bot created directly on a Bitrix24 account, bypassing the platform, has no record in the Vibecode database: the data field is not present in the 409 response, and the transfer returns 404 BOT_NOT_FOUND.

2. Get the target key identifier

targetApiKeyId is the id field of the key record, not the key string. The list is returned by GET /v1/keys to a management key with the vibe:mgmt:keys scope — a portal key cannot get this list, and the response is 401 WRONG_KEY_TYPE. A management key is created in your dashboard, and a read-only key is enough for this step: the list is returned, while such a key cannot modify keys. After the transfer it can be revoked.

The response contains the keys of the management key owner on the specified Bitrix24 account. You recognize your own key by the prefix and suffix fields. The portalId value arrives in the portal.id field of the GET /v1/me response — that call needs no management scopes. The same identifier is returned by GET /v1/portals, but it carries its own vibe:mgmt:portals scope. A Bitrix24 account administrator who transfers a bot to another user's key gets that key identifier from its owner — other users' keys are not returned in the list.

curl -H "X-Api-Key: YOUR_MANAGEMENT_KEY" \
  "https://vibecode.bitrix24.com/v1/keys?portalId=PORTAL_ID"

3. Transfer ownership

curl -X POST https://vibecode.bitrix24.com/v1/bots/42/transfer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetApiKeyId": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33" }'

{
  "success": true,
  "data": {
    "transferred": true,
    "botId": 42,
    "fromApiKeyId": "8c41d5e7-2b90-4a63-b1f5-6d7e9a0c4b12",
    "toApiKeyId": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33"
  }
}

After this response the bot appears in GET /v1/bots for the new key.

4. Check the binding

The transfer changes the binding on the Vibecode side. A separate call checks the new key's access to the bot on the Bitrix24 account. It answers the owner key only, so this step is performed by the owner of the target key: a Bitrix24 account administrator who transferred the bot to another user's key gets 403 BOT_ACCESS_DENIED.

curl -X POST https://vibecode.bitrix24.com/v1/bots/42/reauth \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "validated": true,
    "refreshed": false
  }
}

validated: true confirms that the new key manages the bot on the Bitrix24 account — events, messages and updates work with it again.

Target key requirements

A key is accepted when all conditions are met:

The transfer does not check the target key's access mode — a read-only key is accepted. Managing the bot with such a key is still impossible: step 4 and every later call return 403 WRITE_BLOCKED_READONLY_KEY. Transfer ownership to a key in READWRITE mode.

You can check the key before the call using its record from the GET /v1/keys call in step 2: the state is in the status field, the Bitrix24 account in portalId, the owner in userId, the scopes in scopes, the expiration in expiresAt, the access mode in accessMode.

A key that fails the check is rejected with 400 TARGET_KEY_INVALID, and the cause is returned in the reason field — the causes are listed in the error table of the Bot ownership transfer page.

When this is needed

Three states lead to the same picture — the bot works, and the key does not see it.

The owner key stopped working. The key value was not saved at creation, the key was revoked, or its validity period ended. The bot binding is intact — access is restored by a transfer to a new key.

The bot is registered with another key. This happens when the application is deployed with one key while the bot was registered with another, or when the key was re-created together with the OAuth application. The transfer brings the bot and the working key back together.

The bot belongs to a platform resource. The bot of an AI agent or a managed bot is governed by that resource itself, so a direct transfer returns 409 BOT_TRANSFER_NOT_ALLOWED. Such a bot is restored through its own resource — see AI agents.

Errors

The full code reference — Error codes.

Known specifics

The procedure is safe to repeat from the start. A transfer to a key that already owns the bot does not change the binding. Checking the current state before a repeat is not needed.

The previous key stops seeing the bot immediately. After the transfer the bot disappears from the previous key's GET /v1/bots — its other bots stay in the list. If two processes were polling the bot, only the one working with the new key continues polling.

Registering under a new code creates a different bot. It has its own botId, its own chats and history, while the previous bot stays on the Bitrix24 account and continues to occupy its code.

See also

• Bot ownership transfer
• Bot re-authorization
• Bot list
• Troubleshooting
• Management keys