# Connecting a self-hosted Bitrix24

A self-hosted (on-premise) Bitrix24 is a Bitrix24 that the customer deploys on their own server rather than in the `bitrix24.{ru,de,com,kz,by}` cloud. For Vibecode to work with such a Bitrix24 account — access CRM, tasks, bots, issue webhooks — a **personal developer-key** is needed on the self-hosted Bitrix24 side.

Since 2026-05-11 the connection is done in two clicks, via the companion bot. Previously you had to ask the self-hosted Bitrix24 administrator to manually issue a developer-key and copy-paste the webhook URL to the platform — that flow has been removed.

## How it works

The connection is done once per Bitrix24 account plus one click per user.

### Step 1. Self-hosted Bitrix24 administrator — once per Bitrix24 account

This step is done by any self-hosted Bitrix24 user with the administrator role.

1. Open the self-hosted Bitrix24 admin interface
2. Install the **Vibecode Connector** module (if not already installed) — it is free, available in the Bitrix24 modules section
3. Open the module settings
4. Click the **"Connect the portal to Vibecode"** button
5. Wait for the process to finish (usually 5–15 seconds) — the module registers the Bitrix24 account with Vibecode, issues an admin developer-key, installs the vibecode app, and registers the companion bot

This step is done once per Bitrix24 account. After that, any self-hosted Bitrix24 user can connect themselves to Vibecode via step 2 — there is no need to bother the admin again.

### Step 2. Vibecode user — one click

Once the administrator has done step 1, any Vibecode user (including the administrator themselves) can connect their self-hosted Bitrix24 account.

1. Open Vibecode, go to the [Portals](/auth/portals) section
2. Click **"Connect self-hosted Bitrix24"**
3. Enter the self-hosted Bitrix24 address (for example, `mybox.example.com`) and click "Continue"
4. Vibecode checks that the Bitrix24 account is registered and shows the **"Open the bot in self-hosted Bitrix24"** link
5. Click the link — a chat with the Vibecode companion bot opens in your self-hosted Bitrix24
6. The bot shows a card with your name and email from Vibecode and two buttons: **"Yes, it's me"** / **"No, it's not me"**
7. Click **"Yes, it's me"** — Vibecode issues your personal developer-key and automatically redirects you to the Bitrix24 account dashboard

Done. From this moment your scripts, agents, and apps on Vibecode can access this self-hosted Bitrix24 on your behalf.

## Connection wizard states

During the connection, the wizard on the Vibecode side goes through several states:

| State | What the user sees | What happens |
|---|---|---|
| **A — address entry** | The "Self-hosted Bitrix24 address" field | The user specifies the domain |
| **B — bot opened** | The "Open the bot in self-hosted Bitrix24" link, valid for 10 minutes | A pair-code is created, waiting for confirmation in the bot |
| **C — success** | "Self-hosted Bitrix24 connected", auto-redirect | The user clicked "Yes" in the bot, the developer-key is issued |
| **D — Bitrix24 account not registered** | "Vibecode does not know this self-hosted Bitrix24" with the step 1 instructions | The `vibecodeconnector` module is not activated yet — ask the administrator |
| **E — rejected / expired** | "Confirmation rejected" or "Confirmation code expired" | The user clicked "No" in the bot, or 10 minutes passed — you can start over |

## What to do in common situations

### "Vibecode does not know this self-hosted Bitrix24" (state D)

This Bitrix24 account is not registered with the platform yet. Ask the self-hosted Bitrix24 administrator to perform step 1: install the `vibecodeconnector` module and click "Connect the portal to Vibecode". After that, return to Vibecode and click the **"I've connected — retry"** button.

### The bot says "Binding request rejected" — but you didn't reject anything

Someone else may be trying to bind your self-hosted Bitrix24 to their Vibecode account. If the request came unexpectedly — you were right to click "No". Notify the self-hosted Bitrix24 administrator: a social engineering attempt may be in progress.

### The bot says "Confirmation code expired" — missed the 10 minutes

The pair-code is valid for 10 minutes. If you didn't make it in time — just open Vibecode, click "Connect self-hosted Bitrix24", and go through the process again.

### "The button is outdated" — I click "Yes" but nothing happens

Most likely you reopened an old message from the bot — a new pair-code has already been created in the meantime (for example, if you opened Vibecode in several tabs). Open Vibecode, check that the wizard shows a fresh pair-code, and click the **"Open the bot in self-hosted Bitrix24"** link again.

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

The feature is rolling out gradually. If there is no button in your account — the feature may be fully disabled (`off`) on the platform side; contact the platform administrator.

In **pilot** mode the button is visible to all users with a "beta" mark next to it, and inside the connection window an informational banner "available to a limited number of portals" is shown — this means the feature works, but we are still rolling it out smoothly. In **on** mode the button is shown the same way, without the badge and the banner.

### The bot did not appear in my self-hosted Bitrix24

After step 1, the `vibecodeconnector` module registers the companion bot automatically. If the bot did not appear, an error may have occurred at one of the activation steps (mint admin-key / install app / register bot). The self-hosted Bitrix24 administrator can click "Connect the portal to Vibecode" again — the process is idempotent, a repeated click only runs the steps that failed.

## Security

- **The initiator card in the bot is a protective mechanism**, not cosmetics. The bot always shows the name and email of the Vibecode user who requested the binding. If you don't recognize this user — click "No, it's not me", and the developer-key will not be issued.
- **The pair-code is valid for 10 minutes** and is single-use — after confirmation it is invalidated immediately. Intercepting the link is useless after 10 minutes or after the first confirmation.
- **The developer-key is stored encrypted.** API responses always return only a hint (the last 4 characters); the key itself is not given to any client.
- **SSRF protection.** Addresses like `localhost`, `127.0.0.1`, IP literals, and private ranges are rejected at the entry stage — Vibecode does not allow specifying its own backend instead of a self-hosted Bitrix24.

## After connecting

A connected self-hosted Bitrix24 behaves the same as a cloud Bitrix24 account:

- Create API keys in the [API Keys](/keys) section — they work through the same `/v1/*` endpoints
- Create OAuth apps in the [Authorization Keys](/apps) section — users get their developer-key automatically via the same bot-pairing process
- Run AI agents and the AI Router — the same models and pipelines work for self-hosted Bitrix24 accounts
- Use web search, billing, analytics — without restrictions compared to cloud

Self-hosted specifics (important):

- **Scopes are real.** On a self-hosted Bitrix24, webhook scopes are enforced by the Bitrix24 account itself — calling a method outside its scope returns 403. On cloud, scopes are advisory (Vibecode filters, B24 does not).
- **The plan is always commercial.** A self-hosted Bitrix24 is a paid license, so the Vibecode trial is not activated for such Bitrix24 accounts.
- **Multiple users of one self-hosted Bitrix24** — each does 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](/feedback) section on Vibecode or contact support. In the ticket, specify:

- The self-hosted Bitrix24 address (for example, `mybox.example.com`)
- At which step it got stuck (A / B / C / D / E)
- The error text, if the bot showed one
- The time of the attempt (approximately)

With this information, we can find your request in the audit log and figure it out faster.

## What's next

- [Quick start](./quickstart.md) — create your first key and try the API
- [Keys and authorization](./keys-auth.md) — key types, scopes, limits
- [Entity API](./entity-api.md) — CRUD over Bitrix24 entities
- [Bot platform](./bots.md) — creating chatbots on Vibecode