## Project key for deploy

`POST /v1/cowork/deploy-key`

A Cowork/Code key (scope `vibe:cowork`) works only with the data plane — chat and the Bitrix24 REST proxy — and is blocked on the infrastructure control plane (server creation, deploy, exec, lifecycle) with the response `403 INFRA_FORBIDDEN_FOR_COWORK_KEY`. This endpoint issues a separate **project key with deploy rights**: call it with the same Cowork/Code key, take the `key` field from the response (the body is a flat object, without a `data` wrapper), and use it as the `X-Api-Key` header for all operations under `/v1/infra/*`.

The returned key carries the `vibe:infra` and `vibe:storage` scopes (without `vibe:cowork`), is valid for 7 days, and is bound to the owner and account of the Cowork/Code key. Each call issues a fresh key and revokes the previous project key — only one is ever active.

**Scope:** `vibe:cowork` (the Cowork/Code key you call the endpoint with). The returned key is separate, with the `vibe:infra` + `vibe:storage` scopes.

## Examples

### curl

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

### JavaScript — get the key and deploy with it

```javascript
// 1. Get the project key with the Cowork/Code key
const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/deploy-key', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_COWORK_KEY' },
})
const deployKey = await res.json()

// 2. From here on use the key field (top level) for the infrastructure control plane
const deploy = await fetch('https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/deploy', {
  method: 'POST',
  headers: {
    'X-Api-Key': deployKey.key,          // NOT the Cowork/Code key
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ /* ... */ }),
})
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `key` | string | The raw key. Returned ONCE and cannot be recovered — save it. |
| `apiKeyId` | string | Identifier of the created key |
| `prefix` | string | Key prefix for display |
| `suffix` | string | Last characters of the key for identification |
| `scopes` | array | `["vibe:infra", "vibe:storage"]` |
| `expiresAt` | string | Expiration (ISO 8601), 7 days from issuance |
| `howToUse` | string | A hint for the agent: how to apply the key |

## Response example

```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/*."
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | Invalid API key |
| 402 | `ACCOUNT_FROZEN` | The account balance is exhausted — top up |
| 403 | `INSUFFICIENT_SCOPE` | The key lacks the `vibe:cowork` scope |
| 403 | `COWORK_NOT_ACTIVATED` | No active Cowork/Code subscription for the user and Bitrix24 account |
| 503 | `COWORK_FEATURE_DISABLED` | Cowork/Code is disabled at the platform level |
| 503 | `DEPLOY_KEY_DISABLED` | Self-service issuance of project keys is disabled at the platform level |
| 503 | `INFRA_DISABLED` | Infrastructure is disabled at the platform level — the key would be pointless |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The raw key (`key`) is returned once** — at issuance. It cannot be recovered afterward. Each call issues a new key and revokes the previous project key, so call the endpoint once at the start of the deploy session and use the received key until the end.

**Use the `key` field from the response (top level) for deploy, NOT the Cowork/Code key.** The Cowork/Code key stays for chat and Bitrix24 REST calls; the project key is for `/v1/infra/*`.

**A successful response (200) is the object itself, without a `success` wrapper.** Errors arrive in the envelope `{ success: false, error: { code, message } }`. Determine success by the HTTP status (`res.ok`).

## See also

- [Cowork/Code](/docs/cowork)
- [Infrastructure and deploy](/docs/infra)
- [Errors](/docs/errors)