Zum Inhalt

API-Key-Rotation

Ein API-Key, der über Jahre unverändert bleibt, landet irgendwann dort, wo Sie es nicht vorgesehen hatten -- in einer Logdatei, einem Screenshot, einem alten Repository. Wer seine Keys regelmässig rotiert, begrenzt den Schaden, den ein unbemerkt geleakter Key noch anrichten kann.

Die Rotation legt einen neuen Key an und lässt den alten für ein begrenztes Überlappungsfenster weiterlaufen, sodass Sie den neuen Key ohne Ausfall ausrollen können.

Wann rotieren

  • Routinemässig alle 90 Tage. Das ist die empfohlene Basis für Produktions-Keys.
  • Sofort bei jedem Verdacht, dass ein Key kompromittiert sein könnte -- versehentlich committet, in ein Support-Ticket eingefügt, auf einem Screenshot sichtbar. Warten Sie in diesem Fall nicht auf die nächste geplante Rotation.

Ablauf in vier Schritten

  1. Rotation auslösen. Gehen Sie im Dashboard auf API-Schlüssel und wählen Sie bei dem betreffenden Key Rotieren. Sie können den Rotations-Endpunkt auch direkt aufrufen (siehe unten). Sowohl der alte Key (der Vorgänger) als auch der neue Key (der Nachfolger) funktionieren während des anschliessenden Überlappungsfensters.
  2. Neuen Key ausrollen -- in dem Dienst oder Skript, das bisher den alten Key verwendet hat. Der Nachfolger übernimmt Bezeichnung, Scopes und Umgebung des Vorgängers, sodass ausser dem Austausch des Key-Werts keine weitere Konfiguration nötig ist.
  3. Spalte „Zuletzt genutzt" prüfen, sobald der Rollout abgeschlossen ist. Das ist der einzige verlässliche Nachweis, dass die Migration funktioniert hat: Bewegt sich die Spalte beim alten Key weiterhin, ruft irgendetwas ihn noch auf -- das sollten Sie klären, bevor das Fenster schliesst.
  4. Fenster ablaufen lassen. Ist der alte Key erkennbar ruhig, ist nichts weiter zu tun -- er hört am Ende des Überlappungsfensters automatisch auf zu funktionieren. Ein manueller Widerruf ist nicht nötig.

Nicht raten -- „Zuletzt genutzt" prüfen

„Zuletzt genutzt" ist das einzige verlässliche Signal, dass eine Rotation gefahrlos auslaufen kann. Wer rotiert und sich sofort abwendet, erfährt von einer vergessenen Integration erst, wenn sie ausfällt.

Rotation über die API auslösen

curl -X POST https://api.subscribeflow.net/api/v1/api-keys/KEY_ID/rotate \
  -H "X-API-Key: sf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"overlap_days": 7}'

overlap_days ist optional und akzeptiert Werte von 1 bis 90; ohne Angabe gilt der Plattform-Standard (abfragbar über GET /api/v1/api-keys/rotation-defaults). Die Antwort enthält den Klartext des Nachfolgers sowie einen rotated_from-Block mit den Angaben zum Vorgänger -- der Klartext des neuen Keys wird nur in dieser Antwort gezeigt, speichern Sie ihn also genauso sorgfältig wie bei der Erstanlage.

Der Nachfolger übernimmt ausserdem die Befristung des Vorgängers: War dieser befristet (etwa auf 90 Tage ab seiner eigenen Erzeugung), erhält der Nachfolger dieselbe Dauer, gerechnet ab dem Zeitpunkt der Rotation. War der Vorgänger unbefristet, ist es auch der Nachfolger.

Was die Antwort-Header verraten

Sobald ein Key ein Ablaufdatum trägt, das noch nicht erreicht ist, tragen alle mit ihm authentifizierten Antworten drei Header:

Header Bedeutung
Sunset Das Datum, an dem der Key aufhört zu funktionieren, als HTTP-Datum
Deprecation Immer true, solange der Key ein Ablaufdatum in der Zukunft trägt -- unabhängig davon, ob er rotiert wurde
X-API-Key-Expires-In-Days Verbleibende Tage bis der Key aufhört zu funktionieren

Alle drei sind auch für Browser-Clients lesbar (sie stehen auf der CORS-Expose-Liste), sodass ein Frontend die Warnung direkt anzeigen kann, ohne über einen serverseitigen Proxy zu gehen.

curl -i https://api.subscribeflow.net/api/v1/subscribers?limit=1 \
  -H "X-API-Key: sf_live_..."

# HTTP/1.1 200 OK
# Sunset: Wed, 04 Nov 2026 00:00:00 GMT
# Deprecation: true
# X-API-Key-Expires-In-Days: 7

Sehen Sie diese Header bei einem Key, den Sie nicht als ablaufend erwartet haben, lohnt sich ein Blick ins Dashboard -- möglicherweise wurde er bereits rotiert.

Benachrichtigung

Standardmässig drei Tage vor Ablauf eines Keys verschickt SubscribeFlow je eine Erinnerungs-E-Mail an die Owner der Organisation (der Vorlauf ist serverseitig konfigurierbar, der Versandlauf erfolgt einmal täglich). Sie ist ein Sicherheitsnetz, kein Ersatz dafür, „Zuletzt genutzt" selbst zu prüfen -- wenn sie eintrifft, sollten Sie bereits wissen, ob der Rollout erfolgreich war.

Grenzen

  • Der Klartext des Keys erscheint genau einmal -- bei der Anlage und erneut bei der Rotation. Geht er verloren, rotieren Sie den Key, um einen neuen zu erhalten; der Klartext eines verlorenen Keys lässt sich nicht wiederherstellen.
  • Ein Key lässt sich genau einmal rotieren, solange sein Nachfolger existiert. Müssen Sie erneut rotieren, rotieren Sie den Nachfolger, nicht den ursprünglichen Key. Der Versuch, einen bereits rotierten, widerrufenen oder abgelaufenen Key erneut zu rotieren, schlägt mit einer Fehlermeldung fehl.
  • Das Fenster kann kürzer ausfallen als angefordert. Trug der Vorgänger bereits ein Ablaufdatum, gilt das frühere von beiden: Wer overlap_days: 30 für einen in zwei Tagen ablaufenden Key anfordert, bekommt zwei Tage. Die Antwort nennt im rotated_from-Block das tatsächliche Ablaufdatum.
  • Das Überlappungsfenster wird bei der Rotation festgelegt und lässt sich danach nicht mehr verlängern. Es gibt keine Möglichkeit, dem Vorgänger nachträglich mehr Zeit zu geben -- auch das Rotieren des Nachfolgers ändert am Ablaufdatum des Vorgängers nichts. Wer einen längeren Rollout erwartet, wählt beim Rotieren einen grösseren Wert für overlap_days.