Issue or replace an application key

POST /v1/cowork/applications/:id/key

Issues a key to an application with an empty slot or replaces the one already issued, and returns the new key exactly once. This is how you publish an application added from the catalog: a raw key cannot be recovered, and re-issuing through a management key is not available to a desktop client.

Scope: vibe:cowork (Cowork/Code key) | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

The issued field names the branch that ran: minted — the slot was empty and a key was issued, rotated — the key in the slot was replaced. You cannot know the branch in advance, so the platform decides. The endpoint serves two kinds of callers. The owner of the application gets the key in the application slot. A member of the development team of the application's server gets their own key for that server — the owner's key is neither changed nor shown to them.

Parameters

Request fields (body)

The body is optional: a request without a body and a request with an empty {} object are equivalent. The schema is strict: an extra field returns 400 VALIDATION_ERROR. The body size is limited to 8 KiB.

Examples

The endpoint accepts only a Cowork/Code key, so only two examples are provided. Personal keys and OAuth application keys lack the vibe:cowork scope, so requests using them return 403 INSUFFICIENT_SCOPE.

curl — Cowork/Code key

curl -X POST https://vibecode.bitrix24.com/v1/cowork/applications/APPLICATION_ID/key \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Idempotency-Key: app-key-2026-09-22-01" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript — Cowork/Code key

const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/applications/APPLICATION_ID/key', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_COWORK_KEY',
    'Idempotency-Key': 'app-key-2026-09-22-01',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})

if (!res.ok) {
  const { error } = await res.json()
  throw new Error(`${res.status} ${error.code}`)
}

const { data } = await res.json()

// The raw key arrives once — save it right away
if (data.rawApiKey === null) {
  // This is a retry: the key has already been issued and is not shown again
} else {
  saveKey(data.applicationId, data.rawApiKey)
}

// The previous key works until previousKey.graceUntil — deliver the new key to the server before then
if (data.previousKey?.graceUntil) {
  console.log('The previous key stops working at:', data.previousKey.graceUntil)
}

Response fields

Values of envSync.status. The variable field names the environment variable that was touched, and the reason field refines skipped and recreate_failed.

Response example

Replacing the key in an occupied slot, issued: "rotated":

{
  "success": true,
  "data": {
    "application": {
      "id": "cmud90k3b0009cicg8yxl2rf8",
      "name": "Deal report",
      "description": null,
      "type": "PERSONAL",
      "iconUrl": null,
      "createdAt": "2026-09-22T22:31:23.063Z",
      "updatedAt": "2026-09-22T22:31:23.092Z",
      "viewerState": "owner",
      "pinned": false,
      "author": { "name": "Application author" },
      "isEmbedded": false,
      "openUrl": null,
      "openTarget": null,
      "server": null,
      "sources": { "hasVersions": false, "latestVersionId": null, "latestSavedAt": null },
      "activeOperation": null,
      "key": {
        "slot": "api",
        "present": true,
        "prefix": "vibe_api_…",
        "suffix": "9529",
        "status": "ACTIVE",
        "expiresAt": null,
        "lastUsedAt": null,
        "rotatable": true,
        "rotateBlockedReason": null,
        "affectsShownKey": true
      }
    },
    "applicationId": "cmud90k3b0009cicg8yxl2rf8",
    "issued": "rotated",
    "rawApiKey": "vibe_api_…",
    "key": {
      "id": "b3d37d59-5b50-4e72-aa12-8a2b40a012f8",
      "prefix": "vibe_api_…",
      "suffix": "9529",
      "scopes": ["crm", "vibe:infra", "vibe:storage"],
      "status": "ACTIVE",
      "expiresAt": null,
      "createdAt": "2026-09-22T22:31:23.086Z"
    },
    "previousKey": {
      "id": "5d192322-3ced-438e-bc4f-0cbba01b9937",
      "graceUntil": "2026-09-23T22:31:23.087Z",
      "status": "ACTIVE"
    },
    "envSync": null,
    "warnings": [],
    "warningCodes": []
  }
}

Issuing a key into an empty slot, issued: "minted":

{
  "success": true,
  "data": {
    "application": {
      "id": "cmud90jwg0001cicg4qgipzws",
      "name": "Sales dashboard",
      "description": null,
      "type": "PERSONAL",
      "iconUrl": null,
      "createdAt": "2026-09-22T22:31:22.816Z",
      "updatedAt": "2026-09-22T22:31:22.889Z",
      "viewerState": "owner",
      "pinned": false,
      "author": { "name": "Application author" },
      "isEmbedded": false,
      "openUrl": null,
      "openTarget": null,
      "server": null,
      "sources": { "hasVersions": false, "latestVersionId": null, "latestSavedAt": null },
      "activeOperation": null,
      "key": {
        "slot": "api",
        "present": true,
        "prefix": "vibe_api_…",
        "suffix": "f08a",
        "status": "ACTIVE",
        "expiresAt": null,
        "lastUsedAt": null,
        "rotatable": true,
        "rotateBlockedReason": null,
        "affectsShownKey": true
      }
    },
    "applicationId": "cmud90jwg0001cicg4qgipzws",
    "issued": "minted",
    "rawApiKey": "vibe_api_…",
    "key": {
      "id": "61a91657-2e88-4aeb-848f-1951327efd71",
      "prefix": "vibe_api_…",
      "suffix": "f08a",
      "scopes": ["vibe:infra", "vibe:storage"],
      "status": "ACTIVE",
      "expiresAt": null,
      "createdAt": "2026-09-22T22:31:22.879Z"
    },
    "previousKey": null,
    "envSync": null,
    "warnings": [],
    "warningCodes": []
  }
}

Error response example

403 — the key in the application slot is wider than the calling key:

{
  "success": false,
  "error": {
    "code": "KEY_ROTATE_WIDER_THAN_CALLER",
    "message": "The key in this application slot is wider than your key. Re-issue it from the web cabinet, where the owner sees what the new key will be allowed to do."
  }
}

Errors

The key is minted through the same Bitrix24 channel as in application creation, and its refusals are passed through verbatim. On a self-hosted portal, the key is minted through a separate channel with its own codes, covered in Keys and authorization. The response shape is the same, so branch on error.code.

See Errors for the full list of common API errors.

Known specifics

The issued key's mode is never wider than your key's. The Cowork/Code subscription mode does not affect the key the application owner receives. An empty slot gets a key in the narrower of the mode the account assigns to new keys and the calling key mode: a read-only policy does not refuse the issuance, it narrows it. A replacement gives a key no wider than the current mode of the replaced key and no wider than the caller.

The card tells you in advance whether the call goes through. The key block of the application card carries rotatable — whether this call goes through for you — and rotateBlockedReason with the refusal reason. WIDER_THAN_CALLER means the key in the slot is wider than yours, WRITE_BLOCKED_READONLY_KEY means your key is read-only. Read an unfamiliar reason as "cannot be replaced, reason unknown". The flag reflects what the platform already knows, so false is not a dead end and true is not a guarantee: handle the refusal from the endpoint itself anyway.

Without syncServerEnv the new key does not reach the server. The application keeps the previous key in its environment and starts getting refusals at previousKey.graceUntil — which is not always 24 hours away. Send true unless you have your own way to deliver the key to the server.

On replacement the new key inherits the expiry. A non-expiring key stays non-expiring, and an expiry that has not yet passed is carried over as is. An expiry that has already passed is replaced with the account's default lifetime — the same keyExpiresInDays that the creation parameters return.

A blocked key in the slot does not prevent a replacement. Its live access tokens are revoked rather than moved to the new key.

A development team member gets a key of their own. The key is bound to the application's server and opens only the development routes of that server. Such a call does not change the environment of the owner's server. If the calling key belongs to a Cowork/Code subscription, the member key uses the narrower of the calling key mode and the subscription mode: a read-only subscription produces a read-only member key, even when the calling key itself can change data.

A retry with the same idempotency key does not return the key. A retry with the same body returns 201 with the Idempotent-Replayed: true header. The secret is stored only as a hash, so save rawApiKey right away, in the same response handler.

See also

• Create an application from Cowork/Code
• Application creation parameters
• Application card
• Project deployment key
• Keys and authorization
• Cowork/Code
• Errors