# Revocar una clave de API

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

Revoca una clave de inmediato. La revocación no se puede deshacer; la clave se rechaza como máximo en 30 segundos. Una clave rotada cuyo solapamiento no ha terminado también se revoca de inmediato. Una clave creada en el panel de control, y cada clave rotada desde ella, solo puede revocarse a sí misma o en el panel de control (`permission_escalation`).

## Solicitud

| Parámetro | En | Descripción |
|---|---|---|
| `key_id` | ruta | Identificador de la clave de API (`key_…`). |

Cuerpo:

El cuerpo es opcional; sin él se aplican todos los valores predeterminados.

| Campo | Tipo | Descripción |
|---|---|---|
| `reason` | string | Opcional. `manual` (predeterminado) o `leaked`. |

## Respuesta

`200 OK`. El objeto de clave con `revoked_at` y `revoke_reason` establecidos.

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

## Errores

| HTTP | `code` | Cuándo |
|---|---|---|
| 401 | `unauthenticated` | Falta la clave, no es válida o está revocada. |
| 403 | `insufficient_permissions` | La clave no tiene el permiso necesario. |
| 403 | `permission_escalation` | La solicitud daría a una clave más permisos, un rango de red más amplio o una expiración más tardía de los que tiene la clave llamadora, una clave `restricted` intenta crear, rotar o revocar más allá de sus propios permisos, u otra clave intenta rotar o revocar una clave creada en el panel de control. |
| 404 | `not_found` | La clave no existe en este entorno. |
| 409 | `conflict` | La clave ya está revocada. |
| 422 | `validation_failed` | El cuerpo no es válido: `reason` no es `manual` ni `leaked`. |

## Ejemplo

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