# Révoquer une clé d'API

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

Révoque une clé immédiatement. La révocation est irréversible ; la clé est rejetée en 30 secondes au plus. Une clé renouvelée dont le chevauchement n'est pas terminé est également révoquée aussitôt. Une clé créée dans le tableau de bord, et chaque clé renouvelée à partir de celle-ci, peut être révoquée que par elle-même ou dans le tableau de bord (`permission_escalation`).

## Requête

| Paramètre | Emplacement | Description |
|---|---|---|
| `key_id` | chemin | Identifiant de la clé d'API (`key_…`). |

Corps :

Le corps est facultatif ; sans lui, toutes les valeurs par défaut s'appliquent.

| Champ | Type | Description |
|---|---|---|
| `reason` | string | Facultatif. `manual` (par défaut) ou `leaked`. |

## Réponse

`200 OK`. L'objet clé avec `revoked_at` et `revoke_reason` renseignés.

```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"
}
```

## Erreurs

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `unauthenticated` | La clé est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé n'a pas la permission requise. |
| 403 | `permission_escalation` | La requête donnerait à une clé plus de permissions, une plage de réseau plus large ou une expiration ultérieure que la clé appelante n'en a, une clé `restricted` tente de créer, renouveler ou révoquer au-delà de ses propres permissions, ou une autre clé tente de renouveler ou révoquer une clé créée dans le tableau de bord. |
| 404 | `not_found` | La clé n'existe pas dans cet environnement. |
| 409 | `conflict` | La clé est déjà révoquée. |
| 422 | `validation_failed` | Le corps est invalide : `reason` n'est ni `manual` ni `leaked`. |

## Exemple

```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"}'
```