Для 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присутствует.
Список ботов ключом, который ими не управляет:
{
"success": true,
"data": {
"bots": [],
"users": [],
"hasNextPage": false
}
}
Повторная регистрация с тем же кодом — в поле data приходит существующий бот:
{
"success": false,
"error": {
"code": "BOT_ALREADY_EXISTS",
"message": "Bot with this code already exists"
},
"data": {
"botId": 42,
"code": "support_bot",
"name": "Техподдержка"
}
}
Обращение к этому боту тем же ключом:
{
"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 отвечает отказом в доступе.
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. Администратору, который переносит бота на ключ другого пользователя, идентификатор этого ключа сообщает его владелец — чужие ключи в списке не приходят.
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. Перенести владение
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" }'
{
"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.
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 — сервер не очищает более новое состояние.
{
"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, собственные чаты и история, а прежний бот остаётся на портале и продолжает занимать свой код.