For AI agents: markdown of this page — /docs-content-en/management-keys/delete.md documentation index — /llms.txt

Delete an API key

DELETE /v1/keys/:id

Deletes an API key belonging to the management key owner and revokes the server access tokens it issued. A deleted key cannot be restored through the API — create a new one if needed.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionKey record ID. List: GET /v1/keys

Examples

The request accepts only a management key — see Limitations.

curl — management key

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

JavaScript — management key

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

if (res.status === 204) {
  console.log('Key deleted')
}

Response

A successful deletion returns HTTP status 204 No Content with an empty body. Success is indicated by the status code, not the body.

Response example

http 
HTTP/1.1 204 No Content

Error response example

404 — key not found:

JSON 
{
  "success": false,
  "error": {
    "code": "KEY_NOT_FOUND",
    "message": "API key not found"
  }
}

Errors

HTTP Code Description
HTTP404 CodeKEY_NOT_FOUND DescriptionNo key with this id exists, it belongs to another user, or it is a management key
HTTP409 CodeKEY_HAS_ACTIVE_SERVERS DescriptionServers are managed through the key. Rebind them to another key or delete them, then retry the deletion. In error.details: activeServerCount — the number of servers, servers — up to 10 servers with the fields id, displayName, name, status. The userMessage field is human-readable text
HTTP409 CodeKEY_HAS_LINKED_AGENT DescriptionAn agent or a managed bot is managed through the key. In error.details: linkedAgentCount, linkedBotCount — managed bots and regular chatbots combined, agents — up to 10 agents with the fields id, name, status, bots — up to 10 regular chatbots with the fields botId and bitrixBotId, userMessage — human-readable text. For DELETE /v1/bots/:botId, take the numeric bitrixBotId from the matching details.bots item
HTTP409 CodeKEY_BOT_CLEANUP_PENDING DescriptionA regular chatbot of this key has not yet been removed from the Bitrix24 account. The key and the bot remain. Retry the deletion later
HTTP409 CodeKEY_ROTATION_RECOVERY_REQUIRED DescriptionThe key is the source of an unfinished replacement: the rotation ended with a 500 response or is still running
HTTP409 CodeKEY_ROTATION_RECOVERY_REQUIRED DescriptionThe key is the new key of an unfinished replacement, and something still references it. Only a new key with no references can be deleted — the steps are in Rotate an API key. If such a deletion is refused, contact support
HTTP409 CodeKEY_REVOCATION_RECOVERY_PENDING DescriptionRevocation of the key's access tokens has not finished yet. Retry the deletion
HTTP409 CodeREISSUE_IN_PROGRESS DescriptionAuthorization keys (vibe_app_) only: another operation on this application's key is already running — a rotation, an update or a deletion. Retry the request once it finishes
HTTP409 CodeKEY_NOT_ACTIVE DescriptionThe authorization key (vibe_app_) was deleted or changed after the request started
HTTP409 CodeKEY_NOT_ACTIVE DescriptionThe key's owner, Bitrix24 account or application changed while the deletion was running. Re-read the key with GET /v1/keys/:id
HTTP409 CodeKEY_OPERATION_IN_PROGRESS DescriptionA transfer or revocation is already running on the key. Retry the deletion once it finishes
HTTP409 CodePORTAL_ORIGIN_CUTOVER_BUSY DescriptionThe address of the key's Bitrix24 account is changing. Retry the deletion later
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe key's credentials could not be deleted in Bitrix24. The key is not deleted
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe key's issuance was not completed, and deletion of its webhook in Bitrix24 was not confirmed. The key is not deleted and still counts toward the key limit. Retry the deletion
HTTP503 CodePORTAL_ORIGIN_CUTOVER_UNAVAILABLE DescriptionCould not check whether the address of the key's Bitrix24 account is changing. Retry the deletion later
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe management key that sent the request is in READONLY mode
HTTP403 CodeMANAGEMENT_SCOPE_REQUIRED DescriptionThe management key lacks the vibe:mgmt:keys scope
HTTP401 CodeWRONG_KEY_TYPE DescriptionThe request was sent with a Bitrix24 account key — a personal vibe_api_ key or a vibe_app_ authorization key. The endpoint accepts only a management key
HTTP401 CodeKEY_INACTIVE DescriptionThe management key is revoked or blocked
HTTP401 CodeKEY_EXPIRED DescriptionThe management key has expired
HTTP401 CodeINVALID_API_KEY DescriptionNo key with the given value was found
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

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

Full list of common API errors — Errors.

Known specifics

A key with a regular chatbot is revoked first. If a regular chatbot uses the key, deletion moves the key to REVOKED, removes the bot from the Bitrix24 account, and deletes the key record only after confirmation. A 409 KEY_BOT_CLEANUP_PENDING response means the key is already revoked and will not return to service on its own.

Deletion works on a frozen account too. A frozen balance does not block key deletion, unlike creation, update and rotation.

A blocked key can be deleted. A key in BLOCKED status is deleted the same way as any other. If it has servers, deletion returns 409 KEY_HAS_ACTIVE_SERVERS — replace such a key by rotation, which moves the servers to the new key.

See also