Для AI-агентов: markdown этой страницы — /docs-content/bots/ownership-recovery.md индекс документации — /llms.txt

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

OAuth-бот приложения переносится только на подходящий ключ того же OAuth-приложения (client_id). Восстановите доступ к этому приложению и ключу; пересозданное приложение с другим client_id не может получить владение: 400 TARGET_KEY_INVALID с error.reason=application_mismatch. Если исходное приложение восстановить нельзя, обратитесь в поддержку. Для старых ботов без метки владения приложением, зарегистрированных по токенному контракту, и ботов личного webhook сохраняются прежние правила переноса на подходящий ключ того же портала. Перенос на совместимый ключ сохраняет botId, чаты и историю.

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

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

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

  • 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 и проверьте error.code. Только 409 BOT_ALREADY_EXISTS с data.botId означает, что Вайбкод знает локальную запись другого ключа: переходите к шагу 2. BOT_REGISTRATION_ORIGIN_UNPROVEN не даёт identity для переноса — обратитесь в поддержку для проверки существующей регистрации. BOT_REGISTRATION_CONCURRENT требует заново запросить GET /v1/bots перед повтором; отсутствие data.botId в таком ответе не доказывает отсутствие локального бота. Остальные коды 409 требуют устранить указанную ошибку, а не переносить бота. Регистрация выполняется от лица администратора портала Битрикс24 — иначе Битрикс24 отвечает отказом в доступе.

Terminal
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 означает, что бот уже сохранён за вызывающим ключом и приходит в GET /v1/bots. Перенос не нужен; используйте data.botId в Bot API и не переходите к шагу 2.

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

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

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

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

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

Если целевой ключ у вас на руках, путь короче: вызовите этим ключом любую операцию с ботом. Ответ 403 BOT_ACCESS_DENIED несёт в error.fix.body.targetApiKeyId идентификатор этого ключа, а в error.fix.path — готовый маршрут переноса. Поля приходят, когда этот ключ может сам выполнить перенос, — условия в BOT_ACCESS_DENIED.

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

Terminal
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.

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

Это разрешённая проверка активного бота после переноса. Если бот уже отключён, вызывайте её только после 410 BOT_DISABLED с error.details.reauthAllowed=true; иначе вернётся 409 BOT_REAUTH_NOT_ALLOWED. Параллельная смена владения или состояния даёт 409 BOT_REAUTH_STATE_CHANGED — сервер не очищает более новое состояние.

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

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

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

Для OAuth-бота приложения целевой ключ также должен принадлежать тому же client_id; другое приложение получает 400 TARGET_KEY_INVALID с error.reason=application_mismatch. Ключ принимается, когда выполнены все условия:

Условие Значение
УсловиеСостояние Значение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 — расшифровка причин в таблице ошибок раздела Перенос владения ботом.

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

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

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

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

Бот принадлежит ресурсу платформы. Ботом AI-агента или управляемого бота распоряжается сам ресурс, поэтому прямой перенос отвечает 409 BOT_TRANSFER_NOT_ALLOWED. Такой бот восстанавливается со стороны своего ресурса — см. AI-агенты.

Ошибки

HTTP Код Когда возвращается
HTTP409 КодBOT_ALREADY_EXISTS Когда возвращаетсяКод занят ботом, зарегистрированным другим ключом. Для бота, заведённого через Вайбкод, в data.botId приходит его идентификатор
HTTP409 КодBOT_REGISTRATION_ORIGIN_UNPROVEN Когда возвращаетсяВладение не доказано; перенос не разрешён. Обратитесь в поддержку для проверки существующей регистрации
HTTP409 КодBOT_REGISTRATION_CONCURRENT Когда возвращаетсяЗа время регистрации код занял бот другого ключа. Перед повтором заново запросите GET /v1/bots. Отсутствие data.botId в этом ответе не доказывает, что локального бота нет
HTTP403 КодBOT_ACCESS_DENIED Когда возвращаетсяОбращение к боту ключом, который им не управляет
HTTP401 КодWRONG_KEY_TYPE Когда возвращаетсяСписок ключей запрошен ключом портала — GET /v1/keys отвечает только менеджмент-ключу
HTTP403 КодNOT_BOT_OWNER Когда возвращаетсяПеренос выполняет не владелец бота — нужен тот же пользователь Вайбкод, что у ключа-владельца, или администратор портала
HTTP400 КодTARGET_KEY_INVALID Когда возвращаетсяЦелевой ключ не прошёл проверку, причина в поле reason
HTTP404 КодTARGET_KEY_NOT_FOUND Когда возвращаетсяКлюча с таким targetApiKeyId нет
HTTP409 КодBOT_TRANSFER_NOT_ALLOWED Когда возвращаетсяБот принадлежит AI-агенту или другому ресурсу платформы
HTTP409 КодBOT_TRANSFER_CONFLICT Когда возвращаетсяВладение изменил параллельный запрос — перечитайте текущую привязку и повторите при необходимости
HTTP403 КодWRITE_BLOCKED_READONLY_KEY Когда возвращаетсяКлючом в режиме «только чтение» выполнен пишущий вызов: регистрация, перенос или проверка привязки
HTTP401 КодTOKEN_MISSING Когда возвращаетсяКлюч авторизации vibe_app_ отправлен без заголовка Authorization: Bearer
HTTP410 КодREAUTH_REQUIRED Когда возвращаетсяПроверка на шаге 4 не подтвердила доступ: учётные данные ключа недействительны и не обновляются автоматически. Авторизуйте ключ заново через OAuth или создайте личный ключ заново
HTTP409 КодBOT_REAUTH_NOT_ALLOWED Когда возвращаетсяБот отключён состоянием, для которого повторная авторизация запрещена
HTTP409 КодBOT_REAUTH_STATE_CHANGED Когда возвращаетсяВладение или состояние изменилось во время проверки; более новое состояние сохранено

Полный справочник кодов — Коды ошибок.

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

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

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

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

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