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 the Bitrix24 side.

The 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 shows a "Self-hosted" badge, and the header of its settings reads "Bitrix24 On-premise Edition".

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
  6. Turn on the "Permission source — Vibecode server" toggle. With it, the rights to create keys and apps are set in the Vibecode dashboard. Without it, Bitrix24 checks each employee's right to create incoming webhooks, and an employee without that right will not get a working key. Where the toggle is and what it changes — Rights to create keys and apps

After this step any user of this Bitrix24 can connect themselves — there is no need to contact the administrator again. If the toggle is left off, this holds only for employees who have the right to create incoming webhooks — the administrator grants that right to everyone else.

Step 2. Vibecode user — one confirmation

  1. Open Vibecode and go to the Select Bitrix24 account screen
  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 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
StateAddress check What the user sees"Checking your Bitrix24" What happensThe wizard looks up the registration for the address you entered
StateAwaiting confirmation What the user sees"Confirm it's you", confirmation buttons active for 10 minutes What happensThe request has been sent to the chat with the bot
StateSuccess What the user sees"Bitrix24 connected", countdown before the dashboard opens What happensThe user clicked "Yes, that's me" and the developer key has been issued
StateRegistration not found What the user sees"Vibecode doesn't know this Bitrix24 yet" with the step 1 instructions What happensThe module on the Bitrix24 is not activated yet
StateCompanion bot not connected What the user sees"Companion bot isn't connected yet" What happensThe platform knows the Bitrix24, but there is no bot on it to talk to
StateActivation in progress What the user sees"Connection is being activated" What happensThe companion bot is being installed, or the Bitrix24 is temporarily unavailable
StateDeclined What the user sees"Confirmation declined" What happensThe user clicked "No" in the bot
StateExpired What the user sees"Confirmation timeout" What happensMore than 10 minutes have passed since the request
StateKey not issued What the user sees"Failed to issue the key" with an error code What happensConfirmation 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 being activated"

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

A linking request arrived that you did not send

If you did not start the connection, someone else sent the request to link your Bitrix24 to their Vibecode account. Click "No, that's not me". The bot answers "Request declined": the developer key is not issued, and no more connection requests will be sent to you. If declining was a mistake, click "I changed my mind" under that answer, and requests start arriving again. 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 "This button is no longer valid" — 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" badge, 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 badge or the banner.

The bot did not appear in my Bitrix24

The companion bot is registered automatically in 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.

An employee's key gets no access to Bitrix24 data

Calls the key makes to Bitrix24 return 401 TOKEN_MISSING with the reason WEBHOOK_MINT_REFUSED_BY_PORTAL, and in Cowork/Code the employee cannot reach Bitrix24 data, including their own profile. This means Bitrix24 denied the employee the right to create an incoming webhook.

The administrator turns on the "Permission source — Vibecode server" toggle or adds the employee to the "Who can create incoming webhooks" field. For a Cowork/Code key, the platform then issues the webhook on its own — after a refusal it retries in an hour, in 4 hours and then once a day, so access appears within a day. To get access right away, the employee only needs to sign out of Cowork/Code and sign in again: signing in reissues the key. There is no need to give the employee administrator rights. Both settings are described in Rights to create keys and apps.

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 sent the linking request. 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 to 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 resolves to an internal network address is blocked 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 applications in the Auth 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.
  • On self-hosted, access is set by the license of the installation. The key is issued by the "Vibecode Connector" module on the Bitrix24 side, and the module refuses when REST is unavailable there: the REST module is not loaded, or the license does not allow REST. Installing the application and issuing the key then fail with 403 INT_TARIFF_REQUIRED and a clear message, with no upgrade link. The Vibe+ plan line (INT_VIBE_PLUS_REQUIRED) concerns cloud accounts only — a self-hosted Bitrix24 never receives that code. This is an AI Beta; terms may change at any time. For the full breakdown of access refusals, see Error codes.
  • 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.

Topping up a self-hosted balance

Vibe credits for a self-hosted Bitrix24 are bought from your Vibecode account: "Billing" → "Top Up" → package → "Proceed to payment". The Bitrix24 store for your region opens, and the order already specifies the license of this particular installation.

The invoice for that order is paid by whoever is named in the billing details at checkout, which can be the customer's accounting department or the partner implementing the project. Vibe credits go to the license named in the order, not to whoever paid.

That is why the partner area, where Bitrix24 partners order products for their clients, has no separate "buy for a client" item: the order is always placed from a Vibecode account connected to that installation, and from there it is an ordinary store invoice.

If something went wrong

Open the Ask Support 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