Менеджмент-ключи

Менеджмент-ключи (vibe_live_) не привязаны к одному порталу и предназначены для автоматизации администрирования: управления API-ключами, просмотра порталов и работы с обратной связью.

Отличие от ключей портала

Скоупы менеджмент-ключа

Каждый менеджмент-ключ создаётся с одним или несколькими скоупами. Без нужного скоупа конкретный эндпоинт возвращает 403 MANAGEMENT_SCOPE_REQUIRED — даже если эндпоинт в принципе доступен менеджмент-ключам.

Эндпоинты /v1/me, /v1/guide и /v1/openapi.json доступны любому менеджмент-ключу без отдельного скоупа.

При создании ключа выбирайте только нужные скоупы — если ключ предназначен только для управления API-ключами, скоуп vibe:mgmt:feedback ему не нужен.

Состояние аккаунта владельца

Менеджмент-ключ действует от лица своего владельца, поэтому состояние его аккаунта проверяется на каждом эндпоинте контура — и на чтении, и на записи. Проверка идёт раньше проверки скоупа, поэтому эти коды приходят даже там, где нужного скоупа у ключа нет.

Заморозка распространяется на все операции контура, включая выпуск, перевыпуск и удаление API-ключей.

Доступные эндпоинты

При обращении к эндпоинтам сущностей Битрикс24 возвращается 403 MANAGEMENT_KEY_NO_ENTITY_ACCESS.

`GET /v1/me` — самоописание ключа

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

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/me

Ответ:

{
  "success": true,
  "data": {
    "type": "management",
    "keyPrefix": "vibe_live_abc123",
    "keySuffix": "f9d2",
    "expiresAt": null,
    "scopes": [],
    "capabilities": [
      "GET https://vibecode.bitrix24.tech/v1/me — this endpoint (management key self-description)",
      "GET https://vibecode.bitrix24.tech/v1/guide — full API reference (portal-agnostic)",
      "GET https://vibecode.bitrix24.tech/v1/keys — list APP keys for a portal (requires portalId query param)",
      "POST https://vibecode.bitrix24.tech/v1/keys — create APP key (requires portalId in body)",
      "GET https://vibecode.bitrix24.tech/v1/portals — list your portals",
      "GET https://vibecode.bitrix24.tech/v1/feedback — list ALL platform feedback (management key sees everything)",
      "GET https://vibecode.bitrix24.tech/v1/feedback/:id — feedback details including comment thread",
      "PATCH https://vibecode.bitrix24.tech/v1/feedback/:id — update status/resolution (legacy, prefer /comments)",
      "POST https://vibecode.bitrix24.tech/v1/feedback/:id/comments — post a team comment, changes status"
    ],
    "portals": [
      {
        "id": "portal-uuid",
        "domain": "mycompany.bitrix24.ru",
        "status": "ACTIVE",
        "role": "ADMIN",
        "appKeyCount": 3
      }
    ],
    "totalAppKeys": 3,
    "quickstart": {
      "step1": "GET https://vibecode.bitrix24.tech/v1/portals — list available portals",
      "step2": "GET https://vibecode.bitrix24.tech/v1/keys?portalId=<id> — list APP keys for a portal",
      "step3": "POST https://vibecode.bitrix24.tech/v1/keys { portalId, name, scopes } — create an APP key",
      "step4": "Use the APP key for entity API calls (deals, tasks, etc.)"
    },
    "docs": "https://vibecode.bitrix24.tech/docs/management-keys"
  }
}

В ответе также присутствует объект feedback со справочником эндпоинтов, статусов и фильтров для работы с тикетами обратной связи — он используется AI-моделями для автоматической обработки тикетов.

`GET /v1/guide` — справочник API

Возвращает полный справочник API со всеми сущностями (без фильтрации по скоупам). Используется для подбора нужных эндпоинтов перед созданием API-ключей.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/guide

`GET /v1/openapi.json` — OpenAPI-спецификация

Возвращает машинно-читаемую OpenAPI 3.1 спецификацию платформы Вайбкод.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/openapi.json

`GET /v1/portals` — список порталов

Возвращает порталы, к которым пользователь имеет доступ, с ролью на каждом портале.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/portals

`GET /v1/keys` — список API-ключей портала

Параметр portalId обязателен. Возвращаются ключи владельца менеджмент-ключа на указанном портале — и личные vibe_api_, и ключи авторизации vibe_app_. Значения ключей не возвращаются: свой ключ узнаётся в списке по полям prefix и suffix.

curl -H "X-Api-Key: vibe_live_abc123..." \
  "https://vibecode.bitrix24.tech/v1/keys?portalId=portal-uuid"

{
  "success": true,
  "data": [
    {
      "id": "3f9a1c20-5e6b-4d18-9a77-0c2b8e4f1d33",
      "name": "Бот техподдержки",
      "prefix": "vibe_api_XXXXXXXXX",
      "suffix": "XXXX",
      "type": "APP",
      "userId": "a02e7b64-91c3-4f5a-8d20-7e1b3c95a4dc",
      "portalId": "d41f0b93-6c85-42e7-9a13-58bd0e7c2f46",
      "clientId": null,
      "scopes": ["imbot"],
      "ipWhitelist": [],
      "rateLimit": null,
      "status": "ACTIVE",
      "accessMode": "READWRITE",
      "issuedVia": "legacy",
      "expiresAt": null,
      "lastUsedAt": "2026-07-29T09:12:44.301Z",
      "createdAt": "2026-07-14T08:03:17.118Z",
      "updatedAt": "2026-07-14T08:03:17.118Z"
    }
  ]
}

Отказы этого запроса:

`POST /v1/keys` — создание API-ключа

Создаёт новый API-ключ (vibe_api_) для указанного портала. В теле передаётся portalId, имя и список скоупов. Полный ключ возвращается в поле rawKey один раз — сохраните его сразу.

curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"portalId": "portal-uuid", "name": "My Key", "scopes": ["crm", "task"]}' \
  https://vibecode.bitrix24.tech/v1/keys

По умолчанию к запрошенным правам добавляются четыре платформенных: vibe:infra, vibe:ai, vibe:search, vibe:storage. Ключ из примера выше получит crm, task и эти четыре.

На портале, где администратор выключил работу с серверами, vibe:infra из этого умолчания снимается молча — ключ выпускается с остальными тремя. Отказ 403 INFRA_DISABLED_FOR_PORTAL приходит только на явно запрошенное право.

Нужен ключ ровно с перечисленным — передайте exactScopes: true:

curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"portalId": "portal-uuid", "name": "Storage only", "scopes": ["crm", "vibe:storage"], "exactScopes": true}' \
  https://vibecode.bitrix24.tech/v1/keys

Такой ключ получит только crm и vibe:storage, а на POST /v1/infra/servers и вызовы AI ответит 403. Права такого ключа считаются окончательными: платформа не расширяет их на лету, поэтому GET /v1/me вернёт ровно то, что было сохранено при выпуске.

Дополнительные коды ошибок:

Отказы выписки со статусом 403, 409, 410 и 502 из таблицы выше приходят и на перевыпуске POST /v1/keys/:id/rotate — оба метода выписывают ключ одним и тем же путём. Исключения — 403 PORTAL_TARIFF_UNREADABLE и 403 PORTAL_SUBSCRIPTION_UNREADABLE: это исходы проверки доступа портала, а она к перевыпуску не применяется. Со статусом 402 до перевыпуска доходят только отказы самой выписки, описанные ниже вторым абзацем. Проверка доступа портала на перевыпуск не распространяется. Тело такого отказа несёт необязательное поле error.reason с точной причиной в таксономии платформы, тогда как error.code остаётся прежним. Разбирайте отказ по error.code, а не по тексту message.

Пять отказов со статусом 402 приходят от проверки доступа портала. Какой именно придёт, решает не регион лицензии сам по себе, а то, чем платформа открывает доступ на этом портале: где его открывает подписка — MARKETPLACE_REQUIRED, где тариф Битрикс24 — BY_PAID_ONLY, KZ_PAID_ONLY, UZ_PAID_ONLY или INT_TARIFF_REQUIRED. Ещё два исхода той же проверки идут со статусом 403, и оба означают, что платформе нечего назвать: PORTAL_TARIFF_UNREADABLE — тариф аккаунта прочитать не удалось, PORTAL_SUBSCRIPTION_UNREADABLE — не удалось прочитать состояние подписки. Подписочный MARKETPLACE_REQUIRED приходит только тогда, когда подписка прочитана и её нет. Эта проверка касается только выписки нового ключа: перевыпуск POST /v1/keys/:id/rotate, автоматическое восстановление ключа и передача владения ей не подчиняются, а уже выданные ключи продолжают работать.

Вторая проверка идёт позже и область у неё ШИРЕ: сам Битрикс24 отказывает в выписке, потому что тариф аккаунта не включает Вайбкод. Она срабатывает на всём, что реально выписывает ключ, — на создании, на перевыпуске POST /v1/keys/:id/rotate, на автоматическом восстановлении ключа и на передаче владения. Там, где доступ продаётся, ответ — 402 с кодом тарифного пейвола (BY_PAID_ONLY, KZ_PAID_ONLY или UZ_PAID_ONLY); где предлагать нечего — 502 CONNECTOR_PLAN_REQUIRED из таблицы выше. Любой из этих кодов терминален: повтор не поможет, пока тариф Битрикс24 не сменён.

Права placement, entity и userfieldtype не сохраняются и на успешном пути: у созданного персонального ключа они не вернутся в scopes ответа, даже если были в запросе рядом с правами на данные. userfieldconfig остаётся доступным.

`GET /v1/keys/:id` — данные одного ключа

Возвращает одну запись ключа без его значения. Состав полей тот же, что у GET /v1/keys выше.

curl -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid

`PATCH /v1/keys/:id` — обновление ключа

Можно изменить любое из полей ниже (все необязательны, передавайте только то, что меняете):

Новый список scopes проходит ту же проверку, что и при создании: если после отбрасывания placement, entity и userfieldtype не осталось ни одного права на данные, приходит 400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID.

Если коробочный портал переехал на новый адрес, а вебхук ключа остался выписан на прежний, правка прав отклоняется: приходит 409 PORTAL_ADDRESS_CHANGED. Запрос к порталу не отправляется, права ключа не меняются ни на платформе Вайбкод, ни в Битрикс24. Переподключите ключ и повторите правку — порядок описан в статье Авторизация, ключи и права.

Ключи, выданные платформой на её собственных эндпоинтах, возвращаются в работу по особым правилам. Ключ, оплачиваемый подпиской, снова становится активным значением status и продлевается полем expiresAt только при открытых проверках выдачи: закрытая проверка отвечает 403 со своим кодом — те же коды проверок выдачи, что и на перевыпуске, их таблица в разделе POST /v1/keys/:id/rotate ниже. Остальные такие ключи — настольного приложения Cowork/Code, агента, проектный ключ для деплоя — здесь не возвращаются в работу вовсе: они выдаются заново там, где выдавались.

Режим ключей Cowork/Code живёт на месте — паре сотрудника и портала, общей для всех его устройств. Поэтому смена mode у ключа настольного приложения здесь не проходит вовсе, а у ключа стороннего агента на подписке ограничена режимом места. Запрос с тем же mode, который шлют ради переименования, изменением не считается и проходит.

Сужение срока, отзыв и правка остальных полей работают как раньше — это способ остановить ключ, а не выдать его. Обычных ключей кабинета эти проверки не касаются.

Отдельное ограничение для ключа авторизации (vibe_app_): запрос, который меняет mode, status или expiresAt, не выполняется одновременно с другой операцией над ключом того же приложения.

Коды ниже относятся к любому ключу при соответствующей операции; только REISSUE_IN_PROGRESS ограничен ключом авторизации приложения. В частности, отзыв обычного vibe_api_ тоже может вернуть KEY_MANAGES_FOREIGN_SERVER или KEY_OPERATION_IN_PROGRESS.

curl -X PATCH \
  -H "X-Api-Key: vibe_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"status": "REVOKED"}' \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid

`DELETE /v1/keys/:id` — удаление ключа

Удаляет ключ. Если на ключе есть активные серверы, возвращается 409 KEY_HAS_ACTIVE_SERVERS — серверы нужно удалить первыми. Если ключом управляется агент, управляемый бот или обычный чат-бот, включая отключённую строку Bot Platform, удаление возвращает 409 KEY_HAS_LINKED_AGENT с полями details.linkedAgentCount, details.linkedBotCount (управляемые + обычные чат-боты), списком details.agents и details.bots (до 10 обычных чат-ботов). Для DELETE /v1/bots/:botId берите числовой bitrixBotId из соответствующего элемента details.bots ответа 409.

Ключ, замена которого не завершена, не удаляется: ответ 409 KEY_ROTATION_RECOVERY_REQUIRED. Исключение — новый ключ из ответа 500 на перевыпуске без поля strandedSlots, порядок описан в разделе POST /v1/keys/:id/rotate ниже. Удаление ключа авторизации (vibe_app_) не выполняется одновременно с другой операцией над ключом того же приложения: ответ 409 REISSUE_IN_PROGRESS. Если ключ уже не действует или изменился после начала запроса, ответ 409 KEY_NOT_ACTIVE.

curl -X DELETE \
  -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid

`POST /v1/keys/:id/rotate` — перевыпуск ключа

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

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

Перевыпуск может закончиться ответом 500 — тогда замена отменена, значения нового ключа в ответе нет, но сам новый ключ уже создан. Так бывает в трёх случаях:

• KEY_ROTATE_REVOKE_FAILED — у заблокированного ключа не подтверждено, что его токены доступа погашены.
• KEY_ROTATION_REPOINT_FAILED — не подтверждён перенос привязок на новый ключ.
• KEY_ROTATION_FINALIZE_FAILED — не подтверждено завершение замены.

Идентификатор нового ключа приходит в error.details.orphanKeyId. Поле error.details.strandedSlots появляется, если при отмене что-то не удалось вернуть старому ключу, и перечисляет, что именно. Если поля нет или в списке нет значения previousKeyGrace, старый ключ после отмены сохраняет прежний срок действия. Дальнейшие шаги зависят от поля strandedSlots:

• Поле strandedSlots есть — обратитесь в поддержку. Не удаляйте новый ключ, пока на него что-то ссылается.
• Поля strandedSlots нет — удалите новый ключ запросом DELETE /v1/keys/:id с идентификатором из orphanKeyId. После ответа 204 ещё раз перевыпустите старый ключ. Если удаление ответило 409 KEY_ROTATION_RECOVERY_REQUIRED, обратитесь в поддержку.

Пока замена не завершена, перевыпуск и удаление старого и нового ключа отвечают 409 KEY_ROTATION_RECOVERY_REQUIRED, поэтому повтор перевыпуска без этих шагов не пройдёт. Исключение — удаление нового ключа по второму пункту выше.

Если привязка исходного ключа изменилась во время выписки, ответ — 409 KEY_ROTATION_SOURCE_CHANGED. Если ключ удалён, ответ — 404 KEY_NOT_FOUND. Новый ключ в этих двух случаях не создаётся. Перечитайте актуальную карточку и состояние ключа перед новой операцией.

Отказы перевыпуска при незавершённой замене и одновременных операциях:

Если у прежнего ключа портала остались только права контекста приложения — placement, entity, userfieldtype, — перевыпуск не пройдёт. Набор прав проверяется до обращения к порталу, поэтому на любом аккаунте приходит один и тот же отказ 400 PERSONAL_KEY_WEBHOOK_SCOPES_INVALID. Сначала добавьте прежнему ключу право на данные через PATCH /v1/keys/:id.

Перевыпуск подчиняется требованию подписки маркетплейса наравне с созданием ключа: без действующей подписки приходит 403 B24_MARKET_SUBSCRIPTION_REQUIRED, а в регионах, где доступ определяется платным тарифом Битрикс24, — 403 INT_TARIFF_REQUIRED. Остальные отказы выписки у перевыпуска те же, что у создания, — таблица кодов в разделе POST /v1/keys выше. Не относятся к перевыпуску только четыре отказа со статусом 402: платформенная проверка доступа касается выписки нового ключа. Уже выданные ключи продолжают работать, а перевыпуск возобновляется сразу после активации подписки.

curl -X POST \
  -H "X-Api-Key: vibe_live_abc123..." \
  https://vibecode.bitrix24.tech/v1/keys/key-uuid/rotate

Ключи, выданные платформой на её собственных эндпоинтах, перевыпускаются по особым правилам. У ключа, оплачиваемого подпиской, перенос прав не безусловен: перед перевыпуском проходят те же проверки, что и при выдаче такого ключа, и закрытая проверка отвечает 403 со своим кодом. Остальные такие ключи — настольного приложения Cowork/Code, агента, проектный ключ для деплоя — не перевыпускаются здесь вовсе: они выдаются заново там, где выдавались. Прежний ключ во всех этих случаях продолжает работать.

Обычных ключей кабинета эти проверки не касаются — они перевыпускаются как раньше. Что умеет ключ подписки и как его выписать — Свой агент на подписке.

`GET /v1/feedback` — список тикетов обратной связи

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

curl -H "X-Api-Key: vibe_live_abc123..." \
  "https://vibecode.bitrix24.tech/v1/feedback?status=NEW&page=1&limit=50"

`GET /v1/feedback/:id` — карточка тикета

Возвращает тикет со всей цепочкой комментариев.

`PATCH /v1/feedback/:id` — обновление тикета

Меняет статус и резолюцию тикета.

`POST /v1/feedback/:id/comments` — комментарий к тикету

Добавляет комментарий команды в цепочку и одновременно меняет статус. Используется AI-моделями для ответа пользователю.

Статусы тикетов

Ответ пользователя переводит тикет из AWAITING_USER в NEEDS_REVIEW. Решённый тикет (RESOLVED) ответ автора возвращает в работу — статус тоже становится NEEDS_REVIEW, а отметка о закрытии (resolvedAt, resolvedBy) снимается, текст решения при этом сохраняется. На NEW, REVIEWING и NEEDS_REVIEW статус сохраняется, потому что мяч и без того на стороне команды. Поле updatedAt при этом обновляется всегда, поэтому очередь, отсортированная по нему, показывает новые ответы независимо от статуса.

Категории тикетов

BUG, SUGGESTION, DOCS, CHAT, BOTS, OTHER.

Фильтры списка

?status=NEW&category=BUG&portalId=<uuid>&page=1&limit=50. Параметр limit ограничен значением 100.

Быстрый старт

1. Создайте менеджмент-ключ в личном кабинете (раздел «Менеджмент-ключи»)
2. Получите список порталов: GET /v1/portals
3. Посмотрите существующие ключи на нужном портале: GET /v1/keys?portalId=<id>
4. Создайте API-ключ с нужными скоупами: POST /v1/keys { portalId, name, scopes }
5. Используйте полученный API-ключ (vibe_api_…) для работы с данными Битрикс24

Ограничения

• Менеджмент-ключи не могут обращаться к эндпоинтам сущностей Битрикс24 (/v1/deals, /v1/tasks и другим)
• Для работы с данными используйте API-ключ (vibe_api_) или ключ авторизации (vibe_app_)
• При попытке обратиться к неподдерживаемому эндпоинту возвращается 403 MANAGEMENT_KEY_NO_ENTITY_ACCESS

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

• Ключи и авторизация
• Права на создание ключей и приложений
• Скоупы
• Быстрый старт
• Оптимизация и batch
• Коды ошибок
• Восстановление доступа к боту