API-Schlüssel rotieren

POST /v1/api-keys/{key_id}:rotate · Berechtigung api-keys:write · optional Idempotency-Key

Rotiert einen Schlüssel: Es wird ein NEUER Schlüssel mit demselben Namen, Typ, denselben Berechtigungen und demselben allowed_cidrs erstellt und zurückgegeben. Der alte Schlüssel bleibt für overlap_hours gültig und funktioniert danach nicht mehr.

Neuer Schlüssel. Die Antwort beschreibt den neuen Schlüssel; rotated_from ist die ID des alten Schlüssels, und key enthält den Rohschlüssel genau einmal (Cache-Control: no-store). Stellen Sie ihn bereit und lassen Sie den alten Schlüssel anschließend auslaufen.
Überlappung. Der alte Schlüssel erhält revoked_at in der Zukunft und revoke_reason: rotated; bei overlap_hours: 0 wird er sofort widerrufen.
Keine Rechteausweitung. Ein Schlüssel kann keinen Schlüssel rotieren, dessen Berechtigungen seine eigenen übersteigen, und ein restricted-Schlüssel kann keinen secret-Schlüssel rotieren. Der neue Schlüssel darf nicht nach dem aufrufenden Schlüssel ablaufen, auch dann nicht, wenn ein Schlüssel sich selbst rotiert (eine Laufzeit verlängern Sie im Dashboard). Ein aufrufender Schlüssel mit allowed_cidrs kann nur Schlüssel rotieren, deren Netzwerke innerhalb der eigenen liegen. Ein im Dashboard erstellter Schlüssel sowie jeder daraus rotierte Schlüssel kann nur durch sich selbst oder im Dashboard rotiert werden (permission_escalation). Der neue Schlüssel behält das created_by des alten Schlüssels; der rotierende Schlüssel wird im Audit-Log erfasst.
Idempotente Wiederholung. Eine Wiederholung mit demselben Idempotency-Key lässt key weg und liefert secret_redacted: true.

Anfrage

Parameter	In	Beschreibung
`key_id`	path	ID des API-Schlüssels (`key_…`).

Body:

Der Body ist optional; ohne ihn gelten alle Standardwerte.

Feld	Typ	Beschreibung
`overlap_hours`	integer	Optional, 0–168, Standard 24. Wie viele Stunden der alte Schlüssel gültig bleibt.
`expires_at`	string (date-time)	Optional. Ablauf des NEUEN Schlüssels; Standard ist jetzt + 365 Tage, höchstens das Ablaufdatum des aufrufenden Schlüssels und höchstens 730 Tage.

Antwort

200 OK mit Cache-Control: no-store. Das Objekt des NEUEN Schlüssels zuzüglich 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>"
}

Fehler

HTTP	`code`	Wann
401	`unauthenticated`	Der Schlüssel fehlt, ist ungültig oder widerrufen.
403	`insufficient_permissions`	Der Schlüssel besitzt die erforderliche Berechtigung nicht.
403	`permission_escalation`	Die Anfrage würde einem Schlüssel mehr Berechtigungen, einen breiteren Netzwerkbereich oder ein späteres Ablaufdatum geben, als der aufrufende Schlüssel besitzt. Ein `restricted`-Schlüssel versucht, über seine eigenen Berechtigungen hinaus zu erstellen, zu rotieren oder zu widerrufen, oder ein anderer Schlüssel versucht, einen im Dashboard erstellten Schlüssel zu rotieren oder zu widerrufen.
404	`not_found`	Der Schlüssel existiert in dieser Umgebung nicht.
409	`conflict`	Der Schlüssel ist bereits widerrufen, abgelaufen oder bereits rotiert (nicht aktiv).
409	`api_key_limit_reached`	In der Umgebung sind bereits die maximal 50 aktiven Schlüssel vorhanden.
422	`validation_failed`	Der Body ist ungültig: `overlap_hours` liegt außerhalb von 0–168, oder `expires_at` liegt in der Vergangenheit oder mehr als 730 Tage in der Zukunft.

Beispiel

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