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
| Feld | Beschreibung |
|---|---|
| Name | Eindeutiges Label pro Konto (in manchen Fehlermeldungen der Alias). Erscheint im Request log und in den Analytics-Filtern. |
| Kategorie | Organisationskennzeichnung (siehe Kategorien). Hat keinen Einfluss auf das API-Verhalten. |
| Aktiv | Aktiviert oder deaktiviert den Schlüssel. Inaktive Schlüssel werden sofort mit 401 Inactive API Key abgelehnt. |
| Läuft ab | Optionales Datum, nach dem der Schlüssel nicht mehr funktioniert. Leer lassen für kein Ablaufdatum. |
| Anfragelimits | Optionale 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.
| Kategorie | Typische Verwendung |
|---|---|
production | Live-Traffic, kundengerichtete Systeme |
development | Lokale Entwicklung und Tests |
staging | Pre-Production- und CI-Umgebungen |
| Benutzerdefiniert | Beliebiges 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:
| Kontingent | Fenster |
|---|---|
| Gesamt | Globales Hartlimit im Dashboard. Gesamtlaufzeit: der Schlüssel wird dauerhaft gesperrt, sobald erreicht |
| Täglich | Limit im gleitenden 24h-Fenster. Letzte 24 Stunden (rollierend, nicht Mitternacht bis Mitternacht) |
| Wöchentlich | Limit im gleitenden 7-Tage-Fenster. Letzte 7 Tage (rollierend) |
| Monatlich | Limit 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:
| Feld | Beschreibung |
|---|---|
| Endpunkt | HTTP-Methode und Pfad |
| Status | Antwort-Statuscode |
| Dauer | Zeit bis zum ersten Byte (ms) |
| IP | IP-Adresse des Aufrufers |
| Credits | Fü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
| Aktion | Auswirkung |
|---|---|
| Deaktivieren | Bearbeiten 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öschen | Im 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
| Fehler | Status | Ursache |
|---|---|---|
Invalid API Key | 401 | Schlüssel nicht gefunden oder fehlerhaft |
Inactive API Key | 401 | Schlüssel ist deaktiviert |
Expired API Key | 401 | Schlüssel hat sein Ablaufdatum überschritten |
Rate limit exceeded for the API key: quota … | 401 | Rollierendes Schlüsselkontingent erreicht |
Rate limit exceeded: You've exceeded the … rate limit on your subscription | 401 | Plan-weite Obergrenze pro Sekunde oder Minute |
IP temporarily blocked | 403 | Zu viele fehlgeschlagene Authentifizierungsversuche von derselben IP |
Siehe auch: Best Practices für Sicherheitsrichtlinien und Glossar für Begriffsdefinitionen.