Rotate an API key

POST /v1/keys/:id/rotate

Issues a new API key to replace the previous one with the same settings and moves the previous key's bindings to it.

Parameters

The request body may be empty or {}: body fields are not read, and the new key's settings are taken from the previous one.

Examples

The request accepts only a management key — see Limitations.

curl — management key

curl -X POST "https://vibecode.bitrix24.com/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc/rotate" \
  -H "X-Api-Key: YOUR_MANAGEMENT_KEY"

JavaScript — management key

const res = await fetch('https://vibecode.bitrix24.com/v1/keys/6dbad0ce-79a9-43f5-8ca4-3e1af7ef63bc/rotate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_MANAGEMENT_KEY',
  },
})

const { success, data, error } = await res.json()
if (success) {
  // The new key's value arrives only in this response
  console.log('New key:', data.rawKey)
} else if (error.details?.orphanKeyId) {
  // The replacement was rolled back, the steps are in "Known specifics"
  console.error(error.code, error.details)
}

Response fields

The prefix, suffix and b24Ready fields are not in the response — they arrive in GET /v1/keys/:id.

Response example

201 — the new key is issued:

{
  "success": true,
  "data": {
    "id": "9b1f2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "name": "CRM integration",
    "type": "APP",
    "userId": "fafa9780-eed7-4d29-b040-2448d924f452",
    "portalId": "0d9f7744-f853-47c7-b06e-6f61f9dd1b7f",
    "clientId": null,
    "scopes": ["crm"],
    "ipWhitelist": [],
    "expiresAt": null,
    "rateLimit": null,
    "status": "ACTIVE",
    "lastUsedAt": null,
    "createdAt": "2026-10-29T12:22:53.937Z",
    "updatedAt": "2026-10-29T12:22:53.937Z",
    "accessMode": "READONLY",
    "totalDefault": null,
    "issuedVia": "cloud-shared",
    "rawKey": "vibe_api_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}

Error response example

409 — the previous key is already revoked:

{
  "success": false,
  "error": {
    "code": "KEY_NOT_ACTIVE",
    "message": "Key is no longer active"
  }
}

Errors

Rotation shares its other issuance refusals with creation: both methods issue the key the same way. These are the issuance refusals with status 409, 410 and 502, with status 503 — NETWORK_DEVKEY_REQUIRED and CONNECTOR_KEY_ISSUE_TIMEOUT, and with status 403 — B24_INSUFFICIENT_SCOPE, B24_ACCESS_DENIED and CONNECTOR_KEY_ISSUE_FORBIDDEN. Their descriptions and the error.reason field are in Create an API key. Status 503 arrives both from issuance and from the account address check, so branch on the code, not on the status: PORTAL_ORIGIN_CUTOVER_UNAVAILABLE from the table above may be retried later, while CONNECTOR_KEY_ISSUE_TIMEOUT must not be retried right away — the webhook may already exist on the Bitrix24 account. The check of the Bitrix24 account's access to the platform does not apply to rotation, so 402 INT_TARIFF_REQUIRED and 403 PORTAL_TARIFF_UNREADABLE do not arrive here. With status 402, rotation receives only Bitrix24's own refusal to issue the key due to the plan — INT_VIBE_PLUS_REQUIRED.

The OWNER_DELETED, OWNER_BLOCKED, ACCOUNT_PENDING_ERASURE and B24_USER_DELETED refusals depend on the key owner's account — see Owner account state.

Full list of common API errors — Errors.

Known specifics

What is carried over to the new key. The name, scopes, allowed IP addresses, access mode, individual limit and the totalDefault setting are carried over from the previous key as they are. The previous key's servers, applications, access tokens, deploy operations and bots move to the new one. The expiry is not carried over: the new key does not expire.

The previous key's transition period is up to 24 hours. The previous key keeps working for 24 hours after rotation, then becomes invalid. If its own expiry comes earlier, that expiry is kept: rotation does not extend the key and does not revive an expired one.

A blocked key can be rotated too. Rotation is the only way to replace a key in BLOCKED status; there is no unblocking. The previous key stays blocked and gets no transition period, and its access tokens are revoked rather than moved to the new key.

A 500 response means the new key was created, but the replacement was rolled back. The new key's value is not in the response. Its ID arrives in error.details.orphanKeyId. The error.details.strandedSlots field appears if the rollback could not return something to the previous key, and lists it: applications, servers, accessTokens, deployOperations, bots, previousKeyGrace. If the field is absent or has no previousKeyGrace, the previous key keeps its previous expiry. Next steps:

• The strandedSlots field is present — contact support. Do not delete the new key while anything still points at it.
• The strandedSlots field is absent — delete the new key with DELETE /v1/keys/:id using the ID from orphanKeyId. After the 204 response, rotate the previous key once more. If the deletion returns 409 KEY_ROTATION_RECOVERY_REQUIRED, contact support.

Until the replacement is finished, rotating or deleting either the previous or the new key returns 409 KEY_ROTATION_RECOVERY_REQUIRED, so retrying the rotation without these steps fails. The exception is deleting the new key as described in the second item.

A refusal for a platform-issued key leaves the previous key untouched. On a SYSTEM_KEY_ROTATE_FORBIDDEN refusal or a Cowork/Code subscription refusal, the previous key keeps working. Ordinary dashboard keys are unaffected by these checks. What a subscription key can do — Your own agent on the subscription.

See also

• List Bitrix24 account API keys
• Create an API key
• Get an API key
• Update an API key
• Delete an API key
• Management keys