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 が返されます。

リクエスト

本文:

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

レスポンス

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

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

エラー

例

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