API-Schlüssel: Aufbewahrung und Rotation

Ein API-Schlüssel ist kein technisches Detail der Integration, sondern ein Zahlungsinstrument. Wer die Zeichenfolge des Tokens besitzt, gibt Ihr Guthaben ohne Rückfragen aus: Der Dienst prüft den Wert selbst, nicht die Person an der Tastatur. Entwickler binden Abrechnung, Nummern oder Proxys per API an und erhalten ein Geheimnis, das wie eine gewöhnliche Variable aussieht, tatsächlich aber einer Karte mit Zugriff auf das Geld des Kontos entspricht. Wir erklären, wo er am häufigsten abfließt, wo er richtig aufgehoben ist, wie Sie Zugänge nach Aufgaben und Personen aufteilen und was bei einem Leck zu tun ist.

Der Schlüssel ist gleichbedeutend mit dem Zugriff auf das Guthaben

Ein API-Token bestätigt keine Identität, sondern das Recht, Geld auszugeben. Das System fragt nicht, wer die Anfrage mit diesem Wert geschickt hat, es prüft nur den Wert selbst. Gelangt die Zeichenfolge in fremde Hände, ist das für die API eine ganz normale, legitime Anfrage: Der Kauf einer Nummer, die Miete eines Proxys, eine Abbuchung vom Guthaben – alles läuft wie ein regulärer Vorgang des Kontos. Diebstahl und eigene Nutzung lassen sich anhand der Anfrage nicht unterscheiden. Die einzig funktionierende Absicherung besteht daher darin, das Geheimnis gar nicht erst in fremde Hände gelangen zu lassen, statt eine Fälschung im Nachhinein zu erkennen.

Wo der Schlüssel nicht hingehört

Zugangsgeheimnisse gelangen immer wieder über dieselben Kanäle nach außen. Code-Repository – eine „auf die Schnelle“ für einen Test committete Zeichenfolge bleibt für immer im Versionsverlauf des Repositorys: Das Löschen der Datei in einem neuen Commit entfernt den Wert nicht aus dem früheren Snapshot, und ein freigegebenes oder öffentliches Repository macht aus einem solchen Fund binnen Minuten fremden Zugriff auf das Guthaben. Container-Image – ein Token, das in der Build-Datei fest eingetragen oder als Build-Argument übergeben wurde, setzt sich als Image-Layer fest und wandert mit dem Image in jede Registry, auch in Testumgebungen mit weicheren Zugriffsregeln als in der Produktion.

Client-Code der Seite – alles, was der Browser empfängt und ausführt, kann jeder Besucher über die Entwicklerwerkzeuge lesen; ein Wert, der ohne eigenes Backend als Zwischenschicht an den Server gerichtet wird, ist als Klartext sichtbar. Adresszeile der Anfrage – ein Geheimnis, das als Teil des Pfads oder als Query-Parameter der URL übertragen wird, wird mit der Adresse an all die Orte kopiert, an denen URLs hängen bleiben: in die Protokolle von Webserver und Proxy, in den Browserverlauf, in den Referer-Header beim Klick auf einen Link und manchmal sogar in den Text der Fehlermeldung selbst, wenn der Dienst in der Diagnose die empfangene URL vollständig zurückgibt. Der richtige Ort dafür ist der Request-Header, nicht der Pfad und nicht die Parameterzeile.

Wo der Schlüssel hingehört

Die Grundregel ist einfach: Ein Geheimnis darf nicht als Text im Code oder in einer Konfiguration existieren, die ins Repository committet wird. Der laufende Prozess liest den Wert aus Umgebungsvariablen, die auf Ebene des Servers oder des Orchestrators gesetzt sind, und nicht aus einer Datei neben dem Quellcode. Die Beispielkonfiguration wird mit leeren Werten committet, die Datei mit den produktiven Tokens gelangt dagegen nicht ins Repository – sie steht auf der Liste der ignorierten Pfade. Für Teams, in denen es mehr als ein Geheimnis gibt und diese regelmäßig wechseln, reichen Umgebungsvariablen nicht aus: Es braucht einen eigenen Speicher, der den Wert auf Anfrage herausgibt, ein Zugriffsprotokoll führt und den Zugang entzieht, ohne den Code der Anwendung anzufassen.

Getrennte Schlüssel für Aufgaben und Personen

Ein Token für alles ist die häufigste und teuerste Vereinfachung. Teilen sich Produktionsserver, Testskript und Drittanbieter-Integration denselben Wert, bedeutet der Widerruf bei einem Leck, alles auf einmal anzuhalten: Der laufende Dienst steht zusammen mit der verwundbaren Testumgebung still, aus der das Geheimnis ja gerade abgeflossen ist. Zugänge sollten mindestens entlang zweier Achsen getrennt werden – nach Aufgabe (Produktion, CI, lokale Entwicklung, Partner-Integration) und nach Person oder Team mit Zugriff. Dann ist der Widerruf eines Geheimnisses die Reaktion auf einen konkreten Vorfall und nicht der Stopp der gesamten Abrechnung. Ein zusätzlicher Vorteil: Anhand des Nutzungsprotokolls eines bestimmten Werts sehen Sie, welche Aufgabe das Guthaben verbraucht, und eine Auffälligkeit bei den Ausgaben lässt sich sofort eingrenzen.

Rotation der Schlüssel – planmäßig und im Notfall

Die planmäßige Rotation ist die Ausgabe eines neuen Geheimnisses und der Widerruf des alten nach Zeitplan und nicht erst nach einem Vorfall. Die Reihenfolge ohne Ausfall: den neuen Wert ausstellen, ohne den bisherigen zu widerrufen; ihn in die Konfiguration des Dienstes ausrollen und bestätigen, dass die Anfragen erfolgreich durchlaufen; erst danach das alte Token widerrufen. Zwei gleichzeitig aktive Werte für einen kurzen Übergangszeitraum sind ein normaler Zustand, die Infrastruktur lässt das zu.

Bei Verdacht auf ein Leck ist die Reihenfolge umgekehrt: zuerst widerrufen, dann analysieren. Widerrufen Sie den kompromittierten Schlüssel sofort, auch ohne hundertprozentige Gewissheit – ein Ausfall während der Ausstellung eines neuen Werts ist günstiger als fremde Ausgaben zulasten Ihres Guthabens. Rufen Sie anschließend den Verlauf der Vorgänge für den Zeitraum ab, in dem der Zugang kompromittiert gewesen sein könnte, und gleichen Sie ihn mit dem ab, was Ihr System tatsächlich getan hat. Wurde das Geheimnis neben anderen Zugangsdaten aufbewahrt – dem Passwort desselben Servers, dem Token eines benachbarten Dienstes wie der Proxy-API –, ändern Sie auch diese: Der Abflusskanal beschränkt sich selten auf einen einzigen Wert. Wie Sie nach dem Schlüsselwechsel nicht an das Anfragelimit stoßen, lesen Sie im Artikel Limits und Throttling der API.

Häufig gestellte Fragen

Was ist zu tun, wenn der Schlüssel bereits in einem öffentlichen Repository aufgetaucht ist?

Sofort widerrufen, selbst wenn der Commit mit dem Geheimnis durch den nächsten Commit gelöscht wurde – das Repository speichert alle Versionen der Datei, und das Löschen entfernt den Wert nicht aus dem früheren Snapshot. Stellen Sie einen neuen Schlüssel aus, aktualisieren Sie die Konfiguration des Dienstes und leiten Sie den Datenverkehr erst nach der Prüfung darauf um; den alten Wert markieren Sie als widerrufen, nicht bloß als ungenutzt.

Kann ich einen Schlüssel mit eingeschränkten Rechten statt für die gesamte API ausstellen?

Wenn der Dienst Tokens mit eingeschränktem Geltungsbereich unterstützt – zum Beispiel nur Guthaben abfragen, ohne das Recht auf Abbuchungen –, verwenden Sie genau solche für Aufgaben, die keinen vollen Zugriff benötigen. Gerät ein eingeschränkter Wert in falsche Hände, begrenzt er auch den möglichen Schaden.

Wie oft sollte ich Schlüssel wechseln, wenn es keine Lecks gab?

Der Rhythmus hängt von der Zahl der Personen und Systeme mit Zugriff ab: Je größer der Kreis, desto kürzer das sichere Intervall. Ein vernünftiger Richtwert ist eine Rotation mindestens einmal pro Quartal für produktive Geheimnisse sowie unmittelbar nach dem Ausscheiden jeder Person, die den Wert kannte.

Das Format zur Übergabe des Schlüssels im Request-Header sowie die Antwortcodes beim Widerruf und bei Überschreitung des Limits sind in der Dokumentation der OTP-API beschrieben.