Veille

API-Schlüssel

Erstellen, konfigurieren und verwalten Sie API-Schlüssel über Ihr Dashboard.

API-Schlüssel authentifizieren Ihre Anfragen an die API. Sie verwalten sie vollständig im Dashboard unter API → API-Schlüssel: Legen Sie eine Kategorie fest, schränken Sie die Nutzung mit rollierenden Kontingenten ein, fügen Sie ein Ablaufdatum hinzu und überwachen Sie die Aktivität pro Schlüssel im Request log.

Wie Sie einen Schlüssel in eine Anfrage einbinden, erfahren Sie in der Einführung.

Einen Schlüssel erstellen

Formular öffnen

Gehen Sie in Ihrem Dashboard zu API → API-Schlüssel und klicken Sie auf Neuer API-Schlüssel.

Felder ausfüllen

Tragen Sie unter Name einen Namen ein (eindeutig im Konto), wählen Sie im Tab API-Schlüssel-Optionen eine Kategorie und legen Sie optional Läuft ab und die Anfragelimits fest.

Secret kopieren

Klicken Sie auf API-Schlüssel erstellen. Das Fenster API-Schlüssel erstellt zeigt den vollständigen Schlüssel mit einer Schaltfläche Kopieren: Speichern Sie ihn sofort in einer Umgebungsvariable oder einem Secret-Manager.

Schlüsselfelder

FeldBeschreibung
NameEindeutiges Label pro Konto (in manchen Fehlermeldungen der Alias). Erscheint im Request log und in den Analytics-Filtern.
KategorieOrganisationskennzeichnung (siehe Kategorien). Hat keinen Einfluss auf das API-Verhalten.
AktivAktiviert oder deaktiviert den Schlüssel. Inaktive Schlüssel werden sofort mit 401 Inactive API Key abgelehnt.
Läuft abOptionales Datum, nach dem der Schlüssel nicht mehr funktioniert. Leer lassen für kein Ablaufdatum.
AnfragelimitsOptionale schlüsselspezifische Obergrenzen auf rollierenden Zeitfenstern (siehe Schlüsselkontingente).

Kategorien

Kategorien kennzeichnen Schlüssel für Ihre eigene Organisation. Sie erscheinen in Dashboard-Filtern und Analysen, ändern jedoch nicht, wie die API eine Anfrage verarbeitet.

KategorieTypische Verwendung
productionLive-Traffic, kundengerichtete Systeme
developmentLokale Entwicklung und Tests
stagingPre-Production- und CI-Umgebungen
BenutzerdefiniertBeliebiges Freitext-Label, z. B. sandbox, partner-acme

Behalten Sie einen Schlüssel pro Umgebung, um ihn unabhängig sperren oder rotieren zu können.

Schlüsselkontingente

Jeder Schlüssel kann unabhängige Obergrenzen für das Anfragevolumen haben, die auf rollierenden Fenstern (nicht Kalendergrenzen) durchgesetzt werden:

KontingentFenster
GesamtGlobales Hartlimit im Dashboard. Gesamtlaufzeit: der Schlüssel wird dauerhaft gesperrt, sobald erreicht
TäglichLimit im gleitenden 24h-Fenster. Letzte 24 Stunden (rollierend, nicht Mitternacht bis Mitternacht)
WöchentlichLimit im gleitenden 7-Tage-Fenster. Letzte 7 Tage (rollierend)
MonatlichLimit im gleitenden 30-Tage-Fenster. Letzte 30 Tage (rollierend)

Lassen Sie ein Feld leer, um für dieses Fenster keine Begrenzung anzuwenden. Wenn ein Kontingent erreicht wird, gibt die API 401 mit Rate limit exceeded for the API key: und dem Kontingentnamen in der Meldung zurück:

{ "error": "Rate limit exceeded for the API key: quota total" }

Kontingentzähler werden aus Anfrage-Logs aggregiert und bis zu 24 Stunden gecacht. Die Durchsetzung ist innerhalb dieses Fensters genau, nicht auf die exakte Anfrage.

Schlüsselkontingente unterscheiden sich von planweiten Ratenlimits (Obergrenzen pro Sekunde und Minute, die kontoübergreifend gelten). Beide geben 401 mit einer Meldung zurück, die das erreichte Limit benennt. Details unter Fehlerbehandlung.

Ablaufdatum

Legen Sie ein Ablaufdatum für Schlüssel fest, die in Skripts, CI-Pipelines oder Partner-Integrationen verwendet werden. Nach Ablauf des Datums gibt die API zurück:

{ "error": "Expired API Key" }

HTTP-Status 401. Erstellen und deployen Sie einen Ersatzschlüssel vor dem Ablaufdatum, um Ausfallzeiten zu vermeiden.

Anfrage-Logs

Jede mit einem Schlüssel getätigte Anfrage wird im Dashboard unter API → Request log aufgezeichnet, wo Sie nach API-Schlüssel filtern können. Jeder Eintrag zeigt:

FeldBeschreibung
EndpunktHTTP-Methode und Pfad
StatusAntwort-Statuscode
DauerZeit bis zum ersten Byte (ms)
IPIP-Adresse des Aufrufers
CreditsFür diese Anfrage berechnete Credits

Verwenden Sie Logs, um die Aktivität pro Schlüssel zu prüfen, unerwartete Fehler zu debuggen oder Traffic von kompromittierten Schlüsseln zu identifizieren.

Deaktivieren, archivieren oder löschen

AktionAuswirkung
DeaktivierenBearbeiten Sie den Schlüssel und setzen Sie Aktiv auf Nein. Der Schlüssel wird sofort gesperrt und bleibt in der Liste. Schalten Sie ihn wieder ein, um ihn zu nutzen.
ArchivierenÜber das Zeilenmenü. Der Schlüssel wird gesperrt und aus der Liste ausgeblendet. Archiviert zeigt ihn wieder. Wiederherstellen setzt ihn zurück auf die Liste, weiterhin inaktiv. Der Alias bleibt reserviert. Der Anfrageverlauf bleibt erhalten.
LöschenIm Bearbeitungsfenster. Entfernt den Schlüssel und seine Konfiguration dauerhaft. Nur möglich, wenn der Schlüssel noch nie verwendet wurde.

Archivieren Sie einen bereits genutzten Schlüssel, wenn er aus der Liste verschwinden soll. Deaktivieren Sie ihn, wenn Sie ihn bald wieder einschalten. Ein Schlüssel mit Anfrageverlauf kann nicht gelöscht werden. Der Verlauf bleibt für Abrechnung und Audits erhalten.

Einen Schlüssel rotieren

Ersatzschlüssel erstellen

Gehen Sie in Ihrem Dashboard zu API → API-Schlüssel, klicken Sie auf Neuer API-Schlüssel und geben Sie ihm dieselbe Kategorie und dieselben Anfragelimits unter einem neuen Namen.

Neuen Schlüssel deployen

Aktualisieren Sie die Umgebungsvariable in jedem System, das den alten Schlüssel verwendet, und deployen Sie neu.

Alten Schlüssel deaktivieren

Setzen Sie den alten Schlüssel auf inaktiv, oder archivieren Sie ihn, um ihn aus der Liste auszublenden. Dadurch werden verbleibende Anfragen gesperrt, ohne den Verlauf zu entfernen.

Fehlerreferenz

FehlerStatusUrsache
Invalid API Key401Schlüssel nicht gefunden oder fehlerhaft
Inactive API Key401Schlüssel ist deaktiviert
Expired API Key401Schlüssel hat sein Ablaufdatum überschritten
Rate limit exceeded for the API key: quota …401Rollierendes Schlüsselkontingent erreicht
Rate limit exceeded: You've exceeded the … rate limit on your subscription401Plan-weite Obergrenze pro Sekunde oder Minute
IP temporarily blocked403Zu viele fehlgeschlagene Authentifizierungsversuche von derselben IP

Siehe auch: Best Practices für Sicherheitsrichtlinien und Glossar für Begriffsdefinitionen.

Auf dieser Seite