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