Project deployment key

POST /v1/cowork/deploy-key

A Cowork/Code key with the vibe:cowork scope works with data only — chat and the Bitrix24 REST proxy — and has no access to the infrastructure control plane. Requests to create a server, deploy, execute commands, or manage the server lifecycle all return 403 INFRA_FORBIDDEN_FOR_COWORK_KEY. This endpoint issues a separate project key with deployment rights: call it with the same Cowork/Code key, take the key field from the response — the body is flat, without a data wrapper — and use it as the X-Api-Key header for operations under /v1/infra/* within the key's access mode — see "Known specifics". A subscription key issued for a third-party agent gets no project key from this endpoint, which returns 403 COWORK_HARNESS_KEY_FORBIDDEN: with such a key, deploy from the Cowork/Code desktop app or with an ordinary key that has the vibe:infra scope, see Your own agent on the subscription.

The returned key has the vibe:infra and vibe:storage scopes (without vibe:cowork), is valid for 7 days, and is bound to the same owner and Bitrix24 account as the Cowork/Code key. Each call issues a new key and revokes the previous project key — only one is active at a time. The issued key cannot grant broader access than either the calling Cowork/Code key or the subscription's access mode. The subscription's mode applies to all of the employee's devices on this Bitrix24 account: a read-only subscription yields a read-only deployment key.

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

Examples

Only Cowork/Code keys carry the vibe:cowork scope. Personal keys and OAuth application keys do not have this scope; requests using them return 403 INSUFFICIENT_SCOPE.

curl — Cowork/Code key

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

JavaScript — 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()
// deployKey.key — the project key for calls under /v1/infra/*

Response fields

Response example

{
  "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."
}

Error response example

403 — the request used a third-party agent key issued for the subscription:

{
  "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."
  }
}

Errors

See Errors for the full list of common API errors.

Known specifics

The raw key (key) is returned only once, when it is issued. 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 deployment session and use the key you receive for the rest of the session.

Issuance moves everything that was bound to the previous keys onto the new key. Server ownership, the application card, live access tokens, and the visibility scope of started deployment operations are transferred in the same transaction that issues the key. Therefore, the server list, retrieving a specific server, publishing, and reading an operation's outcome all work under the new key immediately after the response, including container applications in Galaxy mode.

Bindings are transferred from more than just the currently active key. Issuance also transfers bindings from previously revoked project keys for the same owner and Bitrix24 account: up to five keys per call, starting with the most recent. If more keys than that hold bindings, subsequent issuances transfer the rest; no separate action is required. Servers that disappeared from the list after earlier reissues therefore reappear after another key request, without manual action in your Vibecode account.

Exactly one application card moves per call. A key holds a single card slot, so if the owner–account pair has several cards, the first one takes the slot on the new key and the rest stay on their previous keys. The applicationSlotBlocked field in the response tells you that a card stayed on its previous key; the response does not name which card it is, so check which card is visible under the new key.

A project key does not bypass the read-only mode. For a Cowork/Code key in read-only mode, the endpoint answers 403 WRITE_BLOCKED_READONLY_KEY: issuing a key is a write. No new project key is issued, and the one already issued keeps working. A read-and-write key associated with a read-only Cowork/Code subscription gets a project key in READONLY mode — the accessMode field shows it. Such a key can deliver to a server it already owns — these operations are listed on the Access mode page. Requests to create a server, manage its lifecycle, write to source storage, or publish an application return 403 WRITE_BLOCKED_READONLY_KEY. Requesting a new key does not grant broader access and revokes the previous project key. To perform these operations, enable read-and-write access for the subscription by changing the mode of the Cowork/Code desktop key in the API Keys section — or use an ordinary read-and-write key with the vibe:infra scope.

Use the top-level key field from the response for deployment, NOT the Cowork/Code key. Continue using the Cowork/Code key for chat and Bitrix24 REST calls; use the project key for /v1/infra/*.

403 INFRA_FORBIDDEN_FOR_COWORK_KEY is returned for every write operation, not only for deployment. A Cowork/Code key cannot call any /v1/infra/* method except reads (GET). Outside infrastructure, it also cannot publish or unpublish an application or write to source storage. The restriction does not apply to reads, but a Cowork/Code key sees only resources it owns: issuance transfers server ownership to the project key, so the server list is empty and reading a specific server returns 404 NOT_FOUND. Source version history remains available to a Cowork/Code key because access there is determined per employee rather than per key. A demo Bitrix24 plan grants trial access. The key restrictions also distinguish between POST /v1/cowork/activate-market-trial, which requires a Cowork/Code desktop key and does not return this code, and POST /v1/portals/:id/activate-market-trial: an untagged vibe:cowork agent-seat key (purpose = null) reaches this guard and receives INFRA_FORBIDDEN_FOR_COWORK_KEY; a third-party agent subscription key has a non-null purpose and is rejected earlier with PURPOSE_KEY_FORBIDDEN. These endpoints do not activate trial access for an international Bitrix24 account.

The project key never appears in error.details.deployableKeys. The 403 INFRA_FORBIDDEN_FOR_COWORK_KEY error response includes error.details.requiredAction with the steps to take, while deployableKeys lists the owner's ordinary keys that can deploy — up to the five most recent, never the secret itself. For a third-party agent key, requiredAction names the Cowork/Code desktop app and an ordinary key with the vibe:infra scope instead of this endpoint. The key issued by this endpoint has a special-purpose tag, and the filter selects only untagged keys, so an empty list does NOT mean you have nothing to deploy with. Keep using the project key you already have: another request issues a new one and revokes the previous one. The deployableKeys field is absent when the platform cannot resolve the key owner; this differs from an empty list.

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
• Infrastructure
• Errors