## 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 |
|----------|-----|:-----:|----------|
| `id` (path) | string | yes | Key record ID. List: [`GET /v1/keys`](/docs/management-keys/list) |

## Examples

The request accepts only a management key — see [Limitations](/docs/management-keys#limitations).

### curl — management key

```bash
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 |
|------|-----|----------|
| 404 | `KEY_NOT_FOUND` | No key with this `id` exists, it belongs to another user, or it is a management key |
| 409 | `KEY_HAS_ACTIVE_SERVERS` | Servers 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 |
| 409 | `KEY_HAS_LINKED_AGENT` | An 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`](/docs/bots/management/delete), take the numeric `bitrixBotId` from the matching `details.bots` item |
| 409 | `KEY_BOT_CLEANUP_PENDING` | A regular chatbot of this key has not yet been removed from the Bitrix24 account. The key and the bot remain. Retry the deletion later |
| 409 | `KEY_ROTATION_RECOVERY_REQUIRED` | The key is the source of an unfinished replacement: the [rotation](/docs/management-keys/rotate) ended with a `500` response or is still running |
| 409 | `KEY_ROTATION_RECOVERY_REQUIRED` | The 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](/docs/management-keys/rotate). If such a deletion is refused, contact support |
| 409 | `KEY_REVOCATION_RECOVERY_PENDING` | Revocation of the key's access tokens has not finished yet. Retry the deletion |
| 409 | `REISSUE_IN_PROGRESS` | Authorization 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 |
| 409 | `KEY_NOT_ACTIVE` | The authorization key (`vibe_app_`) was deleted or changed after the request started |
| 409 | `KEY_NOT_ACTIVE` | The key's owner, Bitrix24 account or application changed while the deletion was running. Re-read the key with [`GET /v1/keys/:id`](/docs/management-keys/get) |
| 409 | `KEY_OPERATION_IN_PROGRESS` | A transfer or revocation is already running on the key. Retry the deletion once it finishes |
| 409 | `PORTAL_ORIGIN_CUTOVER_BUSY` | The address of the key's Bitrix24 account is changing. Retry the deletion later |
| 502 | `BITRIX_UNAVAILABLE` | The key's credentials could not be deleted in Bitrix24. The key is not deleted |
| 502 | `BITRIX_UNAVAILABLE` | The 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 |
| 503 | `PORTAL_ORIGIN_CUTOVER_UNAVAILABLE` | Could not check whether the address of the key's Bitrix24 account is changing. Retry the deletion later |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The management key that sent the request is in `READONLY` mode |
| 403 | `MANAGEMENT_SCOPE_REQUIRED` | The management key lacks the `vibe:mgmt:keys` scope |
| 401 | `WRONG_KEY_TYPE` | The 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 |
| 401 | `KEY_INACTIVE` | The management key is revoked or blocked |
| 401 | `KEY_EXPIRED` | The management key has expired |
| 401 | `INVALID_API_KEY` | No key with the given value was found |
| 401 | `MISSING_API_KEY` | The `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](/docs/management-keys#owner-account-state).

Full list of common API errors — [Errors](/docs/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](/docs/management-keys/create), [update](/docs/management-keys/update) and [rotation](/docs/management-keys/rotate).

**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](/docs/management-keys/rotate), which moves the servers to the new key.

## See also

- [List Bitrix24 account API keys](/docs/management-keys/list)
- [Get an API key](/docs/management-keys/get)
- [Update an API key](/docs/management-keys/update)
- [Rotate an API key](/docs/management-keys/rotate)
- [Delete a bot](/docs/bots/management/delete)
- [Management keys](/docs/management-keys)