# Восстановление доступа к боту

Бот привязан к тому ключу, которым зарегистрирован, поэтому другой ключ не видит его в списке и не может занять тот же код. Доступ возвращается переносом владения на действующий ключ — бот не пересоздаётся, чаты и история сообщений сохраняются.

## Как выглядит потеря доступа

Признаки приходят все сразу:

- `GET /v1/bots` отвечает успехом и пустым массивом `bots`, хотя бот на портале работает.
- `POST /v1/bots` с тем же `code` отвечает `409 BOT_ALREADY_EXISTS` — код занят.
- `GET /v1/bots/:botId` по идентификатору из ответа `409` отвечает `403 BOT_ACCESS_DENIED`.
- `GET /v1/me` при этом подтверждает, что сам ключ действует: `accessMode` равен `READWRITE`, скоуп `imbot` присутствует.

Список ботов ключом, который ими не управляет:

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

Повторная регистрация с тем же кодом — в поле `data` приходит существующий бот:

```json
{
  "success": false,
  "error": {
    "code": "BOT_ALREADY_EXISTS",
    "message": "Bot with this code already exists"
  },
  "data": {
    "botId": 42,
    "code": "support_bot",
    "name": "Техподдержка"
  }
}
```

Обращение к этому боту тем же ключом:

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

## Почему бот не виден

У бота две разные привязки. Владение закреплено за пользователем Вайбкод и не меняется, когда ключи истекают или отзываются. Привязка к ключу означает другое — каким ключом бот управляется сейчас.

`GET /v1/bots` возвращает записи из базы Вайбкод, отфильтрованные по вызывающему ключу, поэтому бот, зарегистрированный другим ключом, в список не попадает. Остальные операции — события, сообщения, обновление — авторизуются так же и отвечают `403 BOT_ACCESS_DENIED`.

Уникальность кода бота при этом проверяется в границах портала, а не ключа. Отсюда и расхождение: список пуст, а код занят.

Сам бот не затронут. Он остаётся на портале, состоит в тех же чатах и сохраняет историю сообщений — недоступно только управление им через API.

## Как вернуть доступ

Четыре шага. Вызовы к боту выполняются тем ключом, на который переносится владение. Перенос доступен владельцу бота, то есть пользователю Вайбкод, которому принадлежит ключ-владелец. Выполнить перенос может и администратор портала.

### 1. Узнать идентификатор бота

Повторите регистрацию с тем же `code`. Ответ `409` означает, что код занят: идентификатор существующего бота приходит в `data.botId`, и запись бота при этом не меняется. Регистрация выполняется от лица администратора портала Битрикс24 — иначе Битрикс24 отвечает отказом в доступе.

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/bots \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "support_bot", "name": "Техподдержка" }'
```

Ответ `201` вместо `409` означает, что регистрация прошла идемпотентно. Владение при этом не переходит, бот по-прежнему не приходит в `GET /v1/bots`, а его `name`, `type`, `eventMode` и `webhookUrl` обновляются значениями из запроса. Если бот работал в режиме `webhook`, передайте `eventMode` и `webhookUrl` вместе с `code` и `name`, чтобы сохранить доставку событий. Идентификатор бота в этом ответе приходит в `data.botId` — переходите к шагу 2.

Порядок применим к ботам, зарегистрированным через Вайбкод. Бот, заведённый на портале Битрикс24 в обход платформы, в базе Вайбкод записи не имеет: в ответе `409` поле `data` не придёт, а перенос ответит `404 BOT_NOT_FOUND`.

### 2. Узнать идентификатор целевого ключа

`targetApiKeyId` — это поле `id` записи ключа, а не строка ключа. Список отдаёт [`GET /v1/keys`](/docs/management-keys) менеджмент-ключу со скоупом `vibe:mgmt:keys` — ключу портала этот список не доступен, в ответ приходит `401 WRONG_KEY_TYPE`. Менеджмент-ключ создаётся в личном кабинете, и для этого шага достаточно ключа в режиме «только чтение»: список отдаётся, а изменять ключи такой ключ не может. После переноса его можно отозвать.

В ответ приходят ключи владельца менеджмент-ключа на указанном портале. Свой ключ узнаётся по полям `prefix` и `suffix`, `portalId` приходит в поле `portal.id` ответа [`GET /v1/me`](/docs/keys-auth) — этому вызову менеджмент-скоупы не нужны. Тот же идентификатор отдаёт [`GET /v1/portals`](/docs/management-keys), но у него свой скоуп `vibe:mgmt:portals`. Администратору, который переносит бота на ключ другого пользователя, идентификатор этого ключа сообщает его владелец — чужие ключи в списке не приходят.

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

### 3. Перенести владение

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

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

После этого ответа бот приходит в `GET /v1/bots` нового ключа.

### 4. Проверить привязку

Перенос меняет привязку на стороне Вайбкод. Проверяет доступ нового ключа к боту на портале отдельный вызов. Он отвечает только ключу-владельцу, поэтому шаг выполняет владелец целевого ключа: администратор, перенёсший бота на ключ другого пользователя, получит `403 BOT_ACCESS_DENIED`.

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

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

`validated: true` подтверждает, что новый ключ управляет ботом на портале, — с ним снова работают события, сообщения и обновление.

## Требования к целевому ключу

Ключ принимается, когда выполнены все условия:

| Условие | Значение |
|---------|----------|
| Состояние | `ACTIVE` |
| Портал | Тот же портал Битрикс24, что и у бота |
| Владелец | Тот же пользователь Вайбкод, который выполняет перенос. Администратор портала переносит бота на ключ любого пользователя того же портала — этот путь работает с личного ключа `vibe_api_`, роль на портале определяется по нему |
| Скоуп | `imbot` |
| Срок действия | Не закончился |
| Назначение | Ключ общего назначения. Выпущенные платформой служебные ключи не принимаются: у них свой жизненный цикл, и после их ротации бот снова останется без управления |

Режим доступа целевого ключа перенос не проверяет — ключ «только чтение» он примет. Управлять ботом таким ключом всё равно нельзя: шаг 4 и все последующие вызовы ответят `403 WRITE_BLOCKED_READONLY_KEY`. Переносите владение на ключ в режиме `READWRITE`.

Проверить ключ до вызова можно по его записи из `GET /v1/keys` шага 2: состояние приходит в поле `status`, портал — в `portalId`, владелец — в `userId`, скоупы — в `scopes`, срок действия — в `expiresAt`, режим доступа — в `accessMode`.

Ключ, не прошедший проверку, отклоняется с `400 TARGET_KEY_INVALID`, а причина приходит в поле `reason` — расшифровка причин в таблице ошибок раздела [Перенос владения ботом](/docs/bots/management/transfer).

## Когда это нужно

Три состояния приводят к одной картине — бот работает, а ключ его не видит.

**Ключ-владелец перестал работать.** Значение ключа не сохранили при создании, ключ отозван или его срок действия закончился. Привязка бота цела — доступ возвращается переносом на новый ключ.

**Бот зарегистрирован другим ключом.** Так происходит, когда приложение развёрнуто с одним ключом, а бот регистрировался другим, либо когда ключ пересоздали вместе с OAuth-приложением. Перенос собирает бота и рабочий ключ обратно вместе.

**Бот принадлежит ресурсу платформы.** Ботом AI-агента или управляемого бота распоряжается сам ресурс, поэтому прямой перенос отвечает `409 BOT_TRANSFER_NOT_ALLOWED`. Такой бот восстанавливается со стороны своего ресурса — см. [AI-агенты](/docs/agents).

## Ошибки

| HTTP | Код | Когда возвращается |
|------|-----|---------------------|
| 409 | `BOT_ALREADY_EXISTS` | Код занят ботом, зарегистрированным другим ключом. Для бота, заведённого через Вайбкод, в `data.botId` приходит его идентификатор |
| 403 | `BOT_ACCESS_DENIED` | Обращение к боту ключом, который им не управляет |
| 401 | `WRONG_KEY_TYPE` | Список ключей запрошен ключом портала — `GET /v1/keys` отвечает только менеджмент-ключу |
| 403 | `NOT_BOT_OWNER` | Перенос выполняет не владелец бота — нужен тот же пользователь Вайбкод, что у ключа-владельца, или администратор портала |
| 400 | `TARGET_KEY_INVALID` | Целевой ключ не прошёл проверку, причина в поле `reason` |
| 404 | `TARGET_KEY_NOT_FOUND` | Ключа с таким `targetApiKeyId` нет |
| 409 | `BOT_TRANSFER_NOT_ALLOWED` | Бот принадлежит AI-агенту или другому ресурсу платформы |
| 409 | `BOT_TRANSFER_CONFLICT` | Владение изменил параллельный запрос — перечитайте текущую привязку и повторите при необходимости |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключом в режиме «только чтение» выполнен пишущий вызов: регистрация, перенос или проверка привязки |
| 401 | `TOKEN_MISSING` | Ключ авторизации `vibe_app_` отправлен без заголовка `Authorization: Bearer` |
| 410 | `REAUTH_REQUIRED` | Проверка на шаге 4 не подтвердила доступ: учётные данные ключа недействительны и не обновляются автоматически. Авторизуйте ключ заново через OAuth или создайте личный ключ заново |

Полный справочник кодов — [Коды ошибок](/docs/errors).

## Известные особенности

**Порядок безопасно повторять с начала.** Перенос на ключ, который уже владеет ботом, привязку не меняет. Сверять текущее состояние перед повтором не нужно.

**Прежний ключ перестаёт видеть бота сразу.** После переноса бот пропадает из `GET /v1/bots` прежнего ключа — остальные его боты в списке остаются. Если бота опрашивали два процесса, опрос продолжает только тот, что работает новым ключом.

**Регистрация под новым кодом даёт другого бота.** У него собственный `botId`, собственные чаты и история, а прежний бот остаётся на портале и продолжает занимать свой код.

## Смотрите также

- [Перенос владения ботом](/docs/bots/management/transfer)
- [Повторная авторизация бота](/docs/bots/management/reauth)
- [Список ботов](/docs/bots/management/list)
- [Диагностика проблем](/docs/bots/troubleshooting)
- [Менеджмент-ключи](/docs/management-keys)