Проектный ключ для деплоя

POST /v1/cowork/deploy-key

Ключ Cowork/Code со скоупом vibe:cowork работает только с данными — чат и REST-прокси Bitrix24 — а в управляющий контур инфраструктуры не допускается: создание сервера, деплой, выполнение команд и управление жизненным циклом отвечают ему 403 INFRA_FORBIDDEN_FOR_COWORK_KEY. Этот эндпоинт выдаёт отдельный проектный ключ с правом деплоя: вызовите его тем же ключом Cowork/Code, возьмите из ответа поле key — тело плоское, без обёртки data, — и используйте его как заголовок X-Api-Key для операций под /v1/infra/* в пределах режима доступа ключа — см. «Известные особенности». Ключу подписки, выписанному для стороннего агента, эндпоинт проектный ключ не выдаёт и отвечает 403 COWORK_HARNESS_KEY_FORBIDDEN: с таким ключом деплой идёт из настольного приложения Cowork/Code или через обычный ключ со скоупом vibe:infra, см. Свой агент на подписке.

Возвращаемый ключ несёт скоупы vibe:infra и vibe:storage (без vibe:cowork), действует 7 дней и привязан к владельцу и порталу ключа Cowork/Code. На каждый вызов выдаётся свежий ключ, а прежний проектный ключ отзывается — активен всегда только один. Режим доступа ключа не шире вызывающего ключа Cowork/Code и не шире режима места Cowork/Code — режима, общего для всех устройств сотрудника на этом портале: у места в режиме «только чтение» ключ деплоя выходит в том же режиме.

Скоуп: vibe:cowork (ключ Cowork/Code, которым вы вызываете эндпоинт). Возвращаемый ключ — отдельный, со скоупами vibe:infra + vibe:storage.

Примеры

Скоуп vibe:cowork несут только ключи Cowork/Code. У личного ключа и ключа OAuth-приложения его нет, отказ по скоупу — 403 INSUFFICIENT_SCOPE.

curl — ключ Cowork/Code

curl -X POST https://vibecode.bitrix24.tech/v1/cowork/deploy-key \
  -H "X-Api-Key: YOUR_COWORK_KEY"

JavaScript — ключ Cowork/Code

const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/deploy-key', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_COWORK_KEY' },
})
const deployKey = await res.json()
// deployKey.key — проектный ключ для вызовов /v1/infra/*

Поля ответа

Пример ответа

{
  "key": "vibe_api_…",
  "apiKeyId": "796877da-0c3b-409b-900f-b5e0d34a5527",
  "prefix": "vibe_api_…",
  "suffix": "d29c",
  "scopes": ["vibe:infra", "vibe:storage"],
  "expiresAt": "2026-09-29T22:31:18.701Z",
  "accessMode": "READWRITE",
  "repointTruncated": false,
  "applicationSlotBlocked": false,
  "howToUse": "Use this key as the X-Api-Key header for all deploy / provision / exec / server-lifecycle calls under /v1/infra/*. Do NOT use the Co-work key for those. This key expires in 7 days; call POST /v1/cowork/deploy-key again to obtain a fresh one. Keep using the Co-work key for chat and Bitrix24 data calls."
}

Пример ответа при ошибке

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

{
  "success": false,
  "error": {
    "code": "COWORK_HARNESS_KEY_FORBIDDEN",
    "message": "A subscription key issued for an external agent cannot mint a project deploy key. Use the Cowork/Code desktop app."
  }
}

Ошибки

Полный список общих ошибок API — Ошибки.

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

Сырой ключ (key) возвращается один раз — при выдаче. Восстановить его потом нельзя. На каждый вызов выдаётся новый ключ, прежний проектный ключ отзывается, поэтому вызывайте эндпоинт один раз в начале сессии деплоя и используйте полученный ключ до конца.

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

Источник переноса — не только действующий ключ. Выдача забирает связи и с ранее отозванных проектных ключей того же владельца и портала: до пяти ключей за вызов, начиная с самого свежего. Если связей накопилось больше, остаток заберут следующие выдачи, отдельного действия это не требует. Поэтому серверы, пропавшие из выдачи после прежних перевыпусков, возвращаются повторным запросом ключа, а не руками через кабинет.

Карточка приложения переезжает ровно одна за вызов. Ключ держит один слот карточки, поэтому если у пары «владелец и портал» карточек несколько, на свежий ключ встанет первая, а остальные останутся на своих прежних ключах. О том, что карточка осталась на прежнем ключе, говорит поле applicationSlotBlocked в ответе. Какая именно осталась — там не названо, судите по тому, какая карточка видна под новым ключом.

Проектный ключ не обходит режим «только чтение». Ключу Cowork/Code в режиме «только чтение» эндпоинт отвечает 403 WRITE_BLOCKED_READONLY_KEY: выдача ключа — это запись. Новый проектный ключ при этом не выдаётся, а уже выданный продолжает работать. Ключ в режиме «чтение и запись» при месте Cowork/Code в режиме «только чтение» получает проектный ключ в режиме READONLY — это показывает поле accessMode. Таким ключом работает доставка на уже свой сервер — состав этих операций перечислен на странице Режим доступа. Создание сервера, операции жизненного цикла, запись в депо исходников и публикация приложения отвечают ему 403 WRITE_BLOCKED_READONLY_KEY. Повторный запрос режим не расширяет, а прежний проектный ключ отзывает. Для таких операций расширьте место — смените режим ключа десктопа Cowork/Code в разделе Ключи API — или используйте обычный ключ в режиме «чтение и запись» со скоупом vibe:infra.

Для деплоя используйте поле key из ответа (верхний уровень), а НЕ ключ Cowork/Code. Ключ Cowork/Code остаётся для чата и вызовов REST Bitrix24, проектный ключ — для /v1/infra/*.

Отказ 403 INFRA_FORBIDDEN_FOR_COWORK_KEY приходит на любую изменяющую операцию, а не только на деплой. Ключом Cowork/Code закрыты все методы /v1/infra/*, кроме чтений (GET), а за пределами инфраструктуры — публикация и снятие приложения с публикации и запись в депо исходников. На чтениях (GET) запрет не срабатывает вовсе, но видно ключу Cowork/Code только то, что принадлежит ему самому: владение серверами выдача переносит на проектный ключ, поэтому список серверов приходит пустым, а запрос конкретного сервера — 404 NOT_FOUND. Из чтений семейства ключу Cowork/Code остаётся история версий исходников — доступ там решается по сотруднику, а не по ключу. У пробного периода Маркета два эндпоинта, и запрет их разводит. Собственный эндпоинт Cowork/Code POST /v1/cowork/activate-market-trial ключ десктопа как раз требует и этого кода не отдаёт вовсе. Близнец POST /v1/portals/:id/activate-market-trial под запретом: агентскому seat-ключу он отвечает 403 INFRA_FORBIDDEN_FOR_COWORK_KEY, а ключу десктопа — раньше и другим, PURPOSE_KEY_FORBIDDEN.

Проектного ключа в error.details.deployableKeys не бывает. В отказе 403 INFRA_FORBIDDEN_FOR_COWORK_KEY приходит error.details.requiredAction с порядком действий, а deployableKeys перечисляет обычные ключи владельца с правом деплоя — до пяти самых свежих, без самого секрета. Ключу стороннего агента requiredAction называет не этот эндпоинт, а настольное приложение Cowork/Code и обычный ключ со скоупом vibe:infra. Ключ, который выдаёт этот эндпоинт, помечен служебным назначением, а отбор берёт только ключи без пометки, поэтому пустой список НЕ означает «выписывать нечем». Уже выданным проектным ключом продолжайте работать: повторный запрос выдаст новый и отзовёт прежний. Самого поля deployableKeys в ответе нет, когда платформа не смогла определить владельца ключа, — это другой случай, чем пустой список.

Успешный ответ (200) — это сам объект, без обёртки success. Ошибки приходят в конверте { success: false, error: { code, message } }. Определяйте успех по HTTP-статусу (res.ok).

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

• Cowork/Code
• Инфраструктура и деплой
• Ошибки