# Revoca una chiave API

`POST /v1/api-keys/{key_id}:revoke` · permesso `api-keys:write` · `Idempotency-Key` facoltativa

Revoca una chiave immediatamente. La revoca non è annullabile; la chiave viene rifiutata al più tardi entro 30 secondi. Anche una chiave ruotata la cui sovrapposizione non è finita viene revocata subito. Una chiave creata nel dashboard, e ogni chiave ruotata da essa, può essere revocata solo da se stessa o nel dashboard (`permission_escalation`).

## Richiesta

| Parametro | Posizione | Descrizione |
|---|---|---|
| `key_id` | percorso | Identificatore della chiave API (`key_…`). |

Corpo:

Il corpo è facoltativo; senza di esso valgono tutti i valori predefiniti.

| Campo | Tipo | Descrizione |
|---|---|---|
| `reason` | string | Facoltativo. `manual` (predefinito) o `leaked`. |

## Risposta

`200 OK`. L'oggetto chiave con `revoked_at` e `revoke_reason` valorizzati.

```json
{
  "id": "key_0000000000000000000000001z",
  "name": "ci",
  "type": "restricted",
  "permissions": ["users:read"],
  "allowed_cidrs": [],
  "last4": "xxxx",
  "created_by": "key_…",
  "created_at": "2026-10-01T10:00:00Z",
  "expires_at": "2027-10-01T10:00:00Z",
  "last_used_at": null,
  "last_used_ip": null,
  "rotated_from": null,
  "revoked_at": "2026-10-02T10:00:00Z",
  "revoke_reason": "leaked"
}
```

## Errori

| HTTP | `code` | Quando |
|---|---|---|
| 401 | `unauthenticated` | La chiave manca, non è valida o è revocata. |
| 403 | `insufficient_permissions` | La chiave non ha il permesso richiesto. |
| 403 | `permission_escalation` | La richiesta darebbe a una chiave più permessi, un range di network più ampio o una scadenza più tardiva di quelli della chiave chiamante, una chiave `restricted` tenta di creare, ruotare o revocare oltre i propri permessi, oppure un'altra chiave tenta di ruotare o revocare una chiave creata nel dashboard. |
| 404 | `not_found` | La chiave non esiste in questo ambiente. |
| 409 | `conflict` | La chiave è già revocata. |
| 422 | `validation_failed` | Il corpo non è valido: `reason` non è `manual` né `leaked`. |

## Esempio

```bash
curl -X POST "https://api.eu.keenauth.com/v1/api-keys/key_0000000000000000000000001z:revoke" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"leaked"}'
```