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

Менеджмент-ключи (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 и эти четыре.

Нужен ключ ровно с перечисленным — передайте 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 — оба метода выписывают ключ одним и тем же путём. Тело такого отказа несёт необязательное поле error.reason с точной причиной в таксономии платформы, тогда как error.code остаётся прежним. Разбирайте отказ по error.code, а не по тексту message.

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

Права 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.

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

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

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 — серверы нужно удалить первыми. Если ключом управляется агент или бот, удаление возвращает 409 KEY_HAS_LINKED_AGENT с полями details.linkedAgentCount, details.linkedBotCount и списком details.agents — сначала удалите агента или бота.

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

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

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

Если у прежнего ключа портала остались только права контекста приложения — 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
• Коды ошибок
• Восстановление доступа к боту