# Freeze and unfreeze

The freeze mechanism is the vault's kill switch. A frozen key cannot produce signatures until it is unfrozen. You can [freeze](/api-reference#tag/keys) individual keys or all keys belonging to a venue in a single call. See the full [Keys API reference](/api-reference#tag/keys) for both the freeze and unfreeze endpoints.

## Freeze keys

[Freeze keys](/api-reference#tag/keys) to halt all signing for those key IDs or venue immediately.

```
POST /v1/keys/freeze
```

Requires all four authentication headers. The caller's user must have the `freeze_keys` capability granted in the [Administrative Policy](/api-reference#tag/adminpolicies).

At least one of the query parameters (`key_ids` or `venue`) is required. The request body must include a `reason`.

**Query parameters:**

| Parameter | Type | Description |
|---|---|---|
| `key_ids` | string | Comma-separated list of key IDs to freeze |
| `venue` | string | Venue ID: freezes all keys belonging to this venue |

**Request body:**

```json
{ "reason": "Suspicious activity detected on exchange account" }
```

**Example: freeze two keys by ID**

```bash
curl -s -X POST \
  "$CV_BASE/v1/keys/freeze?key_ids=eth-signer,btc-signer" \
  -H "Authorization: ApiKey $API_KEY_UUID" \
  -H "X-Request-Timestamp: $TS_HEX" \
  -H "X-Request-Nonce: $NONCE_HEX" \
  -H "X-Request-Assertion: $ASSERTION" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Suspicious activity detected on exchange account"}'
```

**Example: freeze all keys at a venue**

```bash
curl -s -X POST \
  "$CV_BASE/v1/keys/freeze?venue=binance" \
  -H "Authorization: ApiKey $API_KEY_UUID" \
  -H "X-Request-Timestamp: $TS_HEX" \
  -H "X-Request-Nonce: $NONCE_HEX" \
  -H "X-Request-Assertion: $ASSERTION" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Precautionary freeze while investigating alert"}'
```

This endpoint is asynchronous. If the response is `202`, [poll the request](/api-reference#tag/requests) via `GET /v1/requests/{request_id}` until the status is no longer `"processing"`.

## Unfreeze keys

```
POST /v1/keys/unfreeze
```

Same query parameter options as freeze (`key_ids` or `venue`). No request body is required. The caller must have the `unfreeze_keys` capability.

**Example: unfreeze by key IDs**

```bash
curl -s -X POST \
  "$CV_BASE/v1/keys/unfreeze?key_ids=eth-signer,btc-signer" \
  -H "Authorization: ApiKey $API_KEY_UUID" \
  -H "X-Request-Timestamp: $TS_HEX" \
  -H "X-Request-Nonce: $NONCE_HEX" \
  -H "X-Request-Assertion: $ASSERTION" \
  -H "Content-Type: application/json" \
  -d '{}'
```

:::note
The freeze and unfreeze endpoints accept both query parameters and a JSON body. Send an empty JSON object (`{}`) as the body on unfreeze to satisfy the `Content-Type: application/json` requirement.
:::

## How freezes interact with in-flight signing requests

A freeze takes effect immediately. Any signing request that arrives after the freeze is in place receives a `403` response with `err_type: "forbidden"` and a message indicating the key is frozen.

Signing requests that were already in progress at the moment of freeze complete normally if they passed policy evaluation before the freeze landed. There is no retroactive cancellation of requests that are mid-flight.

## Checking freeze state

The key object returned by `GET /v1/keys/{key_id}` includes:

```json
{
  "is_frozen": true,
  "freeze_reason": "Precautionary freeze while investigating alert"
}
```

You can also filter the key list to frozen keys only:

```bash
curl -s "$CV_BASE/v1/keys?is_frozen=true" \
  -H "Authorization: ApiKey $API_KEY_UUID"
```

## Audit events

Every freeze and unfreeze operation produces audit events:

* `key_frozen` when a freeze completes.
* `key_unfrozen` when an unfreeze completes.

Each event records the actor, the affected key IDs, the reason (for freezes), and the timestamp. See [Export the audit log](/develop/audit-export) to query these events.

## Required permissions

| Action | Required capability |
|---|---|
| Freeze | `freeze_keys` |
| Unfreeze | `unfreeze_keys` |

These capabilities are granted in the Administrative Policy. The caller must be in a group whose policy rule allows the action.