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

`POST /v1/cowork/deploy-key`

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

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

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

## Примеры

### curl

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

### JavaScript — получить ключ и задеплоить им

```javascript
// 1. Получаем проектный ключ ключом 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()

// 2. Дальше используем поле key (верхний уровень) для control-plane инфраструктуры
const deploy = await fetch('https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/deploy', {
  method: 'POST',
  headers: {
    'X-Api-Key': deployKey.key,          // НЕ ключ Cowork/Code
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ /* ... */ }),
})
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `key` | string | Сырой ключ. Возвращается ОДИН раз, восстановить нельзя — сохраните его. |
| `apiKeyId` | string | Идентификатор созданного ключа |
| `prefix` | string | Префикс ключа для отображения |
| `suffix` | string | Последние символы ключа для идентификации |
| `scopes` | array | `["vibe:infra", "vibe:storage"]` |
| `expiresAt` | string | Срок действия (ISO 8601), 7 дней с момента выдачи |
| `howToUse` | string | Подсказка для агента: как применять ключ |

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

```json
{
  "key": "vibe_api_…",
  "apiKeyId": "...",
  "prefix": "vibe_api_…",
  "suffix": "…xy3z",
  "scopes": ["vibe:infra", "vibe:storage"],
  "expiresAt": "2026-07-06T14:05:00.000Z",
  "howToUse": "Use this key as the X-Api-Key header for all deploy / provision / exec / server-lifecycle calls under /v1/infra/*."
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный API-ключ |
| 402 | `ACCOUNT_FROZEN` | Баланс портала исчерпан — пополните счёт |
| 403 | `INSUFFICIENT_SCOPE` | У ключа нет скоупа `vibe:cowork` |
| 403 | `COWORK_NOT_ACTIVATED` | Нет активной подписки Cowork/Code для пары пользователь и портал |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork/Code отключён на уровне платформы |
| 503 | `DEPLOY_KEY_DISABLED` | Самостоятельная выдача проектных ключей отключена на уровне платформы |
| 503 | `INFRA_DISABLED` | Инфраструктура отключена на уровне платформы — ключ не имел бы смысла |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

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

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

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

- [Cowork/Code](/docs/cowork)
- [Инфраструктура и деплой](/docs/infra)
- [Ошибки](/docs/errors)