For AI agents: markdown of this page — /docs-content-en/connect-self-hosted-bitrix24.md documentation index — /llms.txt

Connecting a self-hosted Bitrix24

A self-hosted Bitrix24 is deployed by the customer on their own server rather than in the Bitrix24 cloud. For Vibecode to work with such a Bitrix24 — access CRM, tasks and bots, issue webhooks — a personal developer key is needed on its side.

Connection runs through the companion bot: once for the whole Bitrix24, plus one confirmation per user. In your Vibecode account such a Bitrix24 is labelled twice — its card carries a "Self-hosted" mark, and the header of its settings reads "Self-hosted Bitrix24".

How it works

Step 1. Bitrix24 administrator — once

Any user of the self-hosted Bitrix24 with administrator rights can perform this step.

  1. Open your Bitrix24 admin panel
  2. Install the free "Vibecode Connector" module if it is not there yet — it is in the modules section
  3. Open the module settings
  4. Click "Connect to Vibecode"
  5. Wait for the activation to finish — the module registers the Bitrix24 with the Vibecode platform, issues the administrator's developer key, installs the application and registers the companion bot

After this step any user of this Bitrix24 can connect themselves — there is no need to contact the administrator again.

Step 2. Vibecode user — one confirmation

  1. Open Vibecode and go to Select Bitrix24 account
  2. Click "Connect self-hosted Bitrix24"
  3. Enter the address of your Bitrix24 — for example, mybox.example.com — and click "Connect"
  4. The wizard checks that this Bitrix24 is registered and that the companion bot is installed on it
  5. Click "Confirm in browser" or "Confirm in the desktop app" — a chat with "Vibecode Bot" opens in the Bitrix24 messenger and a linking request arrives there
  6. The request shows a card with your name and email from your Vibecode account and two buttons — "Yes, that's me" and "No, that's not me"
  7. Click "Yes, that's me" — Vibecode issues your personal developer key and opens the dashboard of this Bitrix24

Open the chat wherever you are already signed in to your Bitrix24 — in the desktop app or in the browser. The confirmation buttons stay active for 10 minutes. If the bot message did not arrive, the wizard can send it again.

Done. From now on, your Vibecode scripts, agents and apps can access this Bitrix24 on your behalf.

If you have connected this Bitrix24 before, the wizard skips the bot confirmation and opens the dashboard right away.

Connection wizard states

State What the user sees What happens
Address check "Checking your Bitrix24" The wizard looks up the registration for the address you entered
Awaiting confirmation "Confirm it's you", confirmation buttons active for 10 minutes The request has been sent to the chat with the bot
Success "Bitrix24 connected", countdown before the dashboard opens The user clicked "Yes, that's me", the developer key is issued
Registration not found "Vibecode doesn't know this Bitrix24 yet" with the step 1 instructions The module on the Bitrix24 is not activated yet
Companion bot not connected "Companion bot isn't connected yet" The platform knows the Bitrix24, but there is no bot on it to talk to
Activation in progress "Connection is activating" The companion bot is being installed, or the Bitrix24 is temporarily unavailable
Declined "Confirmation declined" The user clicked "No" in the bot
Expired "Confirmation timeout" More than 10 minutes have passed since the request
Key not issued "Couldn't issue the key" with an error code Confirmation went through, but the developer key could not be issued

What to do in common situations

"Vibecode doesn't know this Bitrix24 yet"

This Bitrix24 is not registered with the platform yet. Ask the administrator to perform step 1: install the "Vibecode Connector" module and click "Connect to Vibecode". After that, return to the wizard and click "I have connected — retry".

"Companion bot isn't connected yet"

Check three conditions: the "Vibecode Connector" module is installed and activated, the "Connect to Vibecode" button has been clicked, and the Bitrix24 allows inbound secure access from the Vibecode platform — a firewall or network address translation (NAT) must not block it.

"Connection is activating"

The companion bot is still being installed, or the Bitrix24 is temporarily unavailable. Retry in a couple of minutes.

The bot says "Linking request declined" — but you didn't decline anything

If you did not start the connection, someone else sent the request to link your Bitrix24 to their Vibecode account. Clicking "No" was the right decision. Notify the Bitrix24 administrator: this is what an attempt to gain access to your Bitrix24 through your account looks like.

"Confirmation timeout" — more than 10 minutes passed

The confirmation code is valid for 10 minutes. Start the connection again — the wizard issues a new link and sends a new request to the bot.

The bot says "Button is stale" — I click "Yes, that's me" and nothing happens

This happens when an old message from the bot is open while the wizard has already created a new confirmation code — for example, if Vibecode is open in several tabs. Return to the wizard, check that it shows a fresh request, and click the confirmation button again.

The bot message did not arrive

The wizard has a "Send again" button. If the chat with the bot is already open, close the messenger tab and click the confirmation button again. When the send attempts are exhausted, start the connection over.

The "Connect self-hosted Bitrix24" button does not appear

The feature is rolling out gradually. If there is no button, it is disabled on the platform side — contact the platform administrator.

While the rollout is in progress, the button is visible with a "beta" mark, and the connection window shows the banner "This feature is currently available to a limited number of Bitrix24 accounts". After the full rollout the button looks the same, without the mark or the banner.

The bot did not appear in my Bitrix24

The companion bot registers itself at step 1. If there is no bot, one of the activation steps did not go through: issuing the administrator key, installing the app, registering the bot. The administrator can click "Connect to Vibecode" again — a repeated click only runs the steps that failed.

Security

  • The initiator card in the bot is a protective mechanism, not decoration. The bot shows the name and email of the Vibecode user who requested the linking. If you don't recognize them — click "No, that's not me", and the developer key will not be issued.
  • The confirmation code is valid for 10 minutes and it is single-use: after confirmation it is invalidated. Intercepting the link is useless after 10 minutes or after the first confirmation.
  • The developer key is stored encrypted. API responses return only a hint — the last 4 characters. The key itself is never returned to any client.
  • Protection against requests into the internal network (SSRF). Addresses like localhost, 127.0.0.1 and addresses written in numeric form are rejected as soon as you enter them. A hostname that leads into the internal network is cut off at the next step — on the outbound call, before the Bitrix24 account is reached.

After connecting

A connected self-hosted Bitrix24 works the same as a cloud one:

  • Create API keys in the API Keys section — they work through the same /v1/* endpoints
  • Create OAuth apps in the Authorization Keys section — users get their developer key automatically, through the same confirmation in the bot
  • Run AI agents and the AI Router — the same models are available
  • Use web search and analytics. The cost is deducted from the Bitrix24 account wallet, the same as for a cloud Bitrix24

How self-hosted differs from cloud:

  • On self-hosted, key scopes are checked by Bitrix24 as well. The platform verifies the scope before the call and answers 403 SCOPE_DENIED — identically for a self-hosted and a cloud Bitrix24. On top of that, on self-hosted the scope set is written into the webhook itself when the key is issued, so an out-of-scope call is rejected by Bitrix24 too, with the code BITRIX_ACCESS_DENIED. Handle both — details in Error codes.
  • A paid self-hosted license by itself grants no access to Vibecode. Access is granted by the Bitrix24 plan: without a commercial plan the self-hosted Bitrix24 does not issue the key. Installing the application and issuing the key fail with 403 INT_TARIFF_REQUIRED and a clear message, with no upgrade link. The .com narrowing to a Vibe+ plan (INT_VIBE_PLUS_REQUIRED) applies to CLOUD accounts only — a self-hosted Bitrix24 never receives that code, and its access is decided by the commercial Bitrix24 plan. This is an AI Beta; terms may change at any time. Full breakdown of access refusals — in Error codes.
  • The wasEverCommercial flag is not one-way. In the GET /v1/me response, for a self-hosted Bitrix24 with neither a commercial plan nor payments found, the value changes once from true to false. Do not rely on its monotonicity.
  • Multiple users of one Bitrix24 — each goes through step 2 individually and gets their own personal developer key. The accounts are independent: revoking one key does not affect the others.

If something went wrong

Open the Feedback section in your Vibecode account or contact support. In the ticket, specify:

  • The Bitrix24 address — for example, mybox.example.com
  • The wizard state at which the connection stopped
  • The error text and its code, if the wizard showed them
  • The time of the attempt

With this information we will find your request in the audit log.

What's next