# API キーをローテーションする

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

キーをローテーションします。同じ名前、種類、権限、`allowed_cidrs` を持つ新しいキーを作成して返します。古いキーは `overlap_hours` の間は有効なままで、その後は使用できなくなります。

- **新しいキー。** レスポンスには新しいキーが含まれます。`rotated_from` には古いキーの ID が入り、`key` には生のキーが一度だけ含まれます(`Cache-Control: no-store`)。新しいキーをデプロイしたあと、古いキーを失効させてください。
- **重複期間。** 古いキーには将来の `revoked_at` が設定され、`revoke_reason: rotated` になります。`overlap_hours: 0` の場合は直ちに取り消されます。
- **権限の昇格なし。** 自身より多くの権限を持つキーはローテーションできません。`restricted` キーは `secret` キーをローテーションできません。新しいキーの有効期限は、呼び出し元のキーの有効期限を超えられません。キーが自身をローテーションする場合も同様です(有効期限の延長はダッシュボードで行ってください)。`allowed_cidrs` を持つ呼び出し元のキーは、自身のネットワーク内に制限されたキーだけをローテーションできます。ダッシュボードで作成されたキーと、そこからローテーションされたすべてのキーは、自身またはダッシュボードからのみローテーションできます(`permission_escalation`)。新しいキーは古いキーの `created_by` を引き継ぎます。ローテーションを実行したキーは監査ログに記録されます。
- **冪等な再実行。** 同じ `Idempotency-Key` での再実行では `key` が省略され、`secret_redacted: true` が返されます。

## リクエスト

| パラメーター | 配置 | 説明 |
|---|---|---|
| `key_id` | path | API キーの ID(`key_…`)。 |

本文:

本文は省略可能です。省略するとすべての既定値が適用されます。

| フィールド | 型 | 説明 |
|---|---|---|
| `overlap_hours` | integer | 省略可。0〜168、既定値は 24。古いキーが有効なままでいる時間数です。 |
| `expires_at` | string (date-time) | 省略可。新しいキーの有効期限です。既定値は現在から 365 日後で、呼び出し元のキーの有効期限以内、かつ最大 730 日までです。 |

## レスポンス

`200 OK`、`Cache-Control: no-store`。新しいキーのオブジェクトと `key` を返します。

```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": "key_…",
  "revoked_at": null,
  "revoke_reason": null,
  "key": "<shown once>"
}
```

## エラー

| HTTP | `code` | 発生条件 |
|---|---|---|
| 401 | `unauthenticated` | キーが存在しない、無効である、または取り消されています。 |
| 403 | `insufficient_permissions` | キーに必要な権限がありません。 |
| 403 | `permission_escalation` | リクエストにより、呼び出し元のキーより多くの権限、より広いネットワーク範囲、またはより後の有効期限が付与されることになる場合、`restricted` キーが自身の権限を超えて作成、ローテーション、取り消しを行おうとした場合、または他のキーがダッシュボードで作成されたキーをローテーションまたは取り消そうとした場合。 |
| 404 | `not_found` | この環境にキーが存在しません。 |
| 409 | `conflict` | キーはすでに取り消されている、期限切れである、またはすでにローテーション済みです(有効ではありません)。 |
| 409 | `api_key_limit_reached` | 環境にすでに上限の 50 個の有効なキーがあります。 |
| 422 | `validation_failed` | 本文が無効です。`overlap_hours` が 0〜168 の範囲外である、または `expires_at` が過去、もしくは 730 日を超えて先の日時になっています。 |

## 例

```bash
curl -X POST "https://api.eu.keenauth.com/v1/api-keys/key_0000000000000000000000001z:rotate" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"overlap_hours":24}'
```