> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Disabling and deleting a key

> Disabling, the deletion window that makes a key recoverable, and what cancelling does not give back.

## Turning a key off

```mermaid theme={null}
stateDiagram-v2
    [*] --> enabled: create
    enabled --> disabled: disable
    disabled --> enabled: enable
    enabled --> pending_deletion: schedule-deletion
    disabled --> pending_deletion: schedule-deletion
    pending_deletion --> disabled: cancel-deletion
    pending_deletion --> [*]: window elapses
```

<Columns cols={2}>
  <Card title="Disable" icon="pause">
    `POST /v1/keys/{key_id}/disable` refuses every crypto operation with
    `409 KMS_KEY_DISABLED` while leaving the material intact. This is the
    reversible move: stop a suspected-compromised key now, keep the ability to
    read historical ciphertext after re-enabling.
  </Card>

  <Card title="Schedule deletion" icon="clock">
    `POST /v1/keys/{key_id}/schedule-deletion` starts a countdown.
    `pending_window_in_days` is **7 to 30, defaulting to 7**. The key refuses
    crypto operations for the whole window, then the material and the record
    are destroyed.
  </Card>
</Columns>

<Tabs>
  <Tab title="Console">
    Open the key from **KMS**. **Disable** and **Enable** are in
    the header. **Schedule key deletion** sits in the **Danger zone** on the
    **Settings** tab: it takes a **Pending window (days)** and makes you type
    the key's name back before **Schedule Deletion** is accepted.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST /v1/keys/{key_id}/schedule-deletion
    { "pending_window_in_days": 30 }
    ```

    `pending_window_in_days` is optional — omit it and you get the 7-day
    minimum, which is the shortest window, not the safest one.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic kms key schedule-deletion <key-id> --pending-window-in-days 30
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    key, err := kms.New(cfg).ScheduleKeyDeletion(ctx, keyID, &kms.ScheduleKeyDeletionRequest{
        PendingWindowInDays: basaltic.Int(30),
    })
    ```
  </Tab>
</Tabs>

<Warning>
  Deletion destroys the key material. Every ciphertext ever produced under the
  key — including every data key you wrapped with it — becomes permanently
  unreadable. The window exists because that is not undoable afterwards, so
  use it: schedule the deletion, watch for what breaks, and only let it elapse
  when nothing does.
</Warning>

### Cancelling

<Tabs>
  <Tab title="Console">
    A key inside the window shows **Cancel Deletion** in its header, where
    **Disable** or **Enable** would otherwise be.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST /v1/keys/{key_id}/cancel-deletion
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic kms key cancel-deletion <key-id>
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    key, err := kms.New(cfg).CancelKeyDeletion(ctx, keyID)
    ```
  </Tab>
</Tabs>

Cancelling exits the window at any point before `deletion_scheduled_at`.

<Note>
  A cancelled key comes back **`disabled`, not `enabled`**. Nothing starts
  working again until you explicitly call `enable`. The window was entered
  because someone wanted the key gone; recovering it should not silently
  restore traffic to it.
</Note>

Two consequences of how quota is accounted are worth knowing before you rely on
cancelling:

* Scheduling a deletion **releases the key's quota immediately**, so you can
  create a replacement inside the same limit without waiting out the window.
* Cancelling therefore has to take that quota back, and **fails with
  `403 QUOTA_EXCEEDED` if your account is now at its limit**. If you created a
  replacement key, free a slot before you cancel.

<Warning>
  A key in `pending_deletion` no longer reserves its **name**, so a new key can
  be created with the same one right away. Because a KMS CRN is built from the
  name (`crn:kms:<region>:<account>:key/<name>`), the old key and the new key
  then share a CRN, and an IAM policy naming it matches both. Give the
  replacement a different name if that distinction matters to your policies.
</Warning>