# API キーを失効

`POST /v1/api-keys/{key_id}:revoke` · 権限 `api-keys:write` · 任意の `Idempotency-Key`

キーを即時に失効させます。失効は取り消せず、キーは遅くとも 30 秒以内に拒否されます。オーバーラップが終わっていないローテーション済みキーも直ちに失効します。ダッシュボードで作成されたキーと、そこからローテーションされたすべてのキーは、自身またはダッシュボードでのみ失効できます (`permission_escalation`)。

## リクエスト

| パラメータ | 場所 | 説明 |
|---|---|---|
| `key_id` | パス | API キー ID (`key_…`)。 |

ボディ:

ボディは任意です。省略するとすべて既定値が適用されます。

| フィールド | 型 | 説明 |
|---|---|---|
| `reason` | string | 任意。`manual` (既定) または `leaked`。 |

## レスポンス

`200 OK`。`revoked_at` と `revoke_reason` が設定されたキーオブジェクト。

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

## エラー

| HTTP | `code` | 発生条件 |
|---|---|---|
| 401 | `unauthenticated` | キーがない、無効、または失効しています。 |
| 403 | `insufficient_permissions` | キーに必要な権限がありません。 |
| 403 | `permission_escalation` | リクエストが呼び出し元キーより多くの権限、より広いネットワーク範囲、またはより遅い有効期限をキーに与えることになる、`restricted` キーが自身の権限を超えて作成、ローテーション、失効を行おうとしている、または別のキーがダッシュボードで作成されたキーをローテーションまたは失効させようとしています。 |
| 404 | `not_found` | この環境にキーが存在しません。 |
| 409 | `conflict` | キーは既に失効しています。 |
| 422 | `validation_failed` | ボディが不正です。`reason` が `manual` でも `leaked` でもありません。 |

## 例

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