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 über das Dashboard: 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 über Anfrage-Logs.
Wie Sie einen Schlüssel in eine Anfrage einbinden, erfahren Sie in der Einführung.
Einen Schlüssel erstellen
Formular öffnen
Gehen Sie zu Dashboard → API-Schlüssel → Neu.
Felder ausfüllen
Geben Sie dem Schlüssel einen Alias (eindeutiges Label für Ihre eigene Referenz), wählen Sie eine Kategorie und konfigurieren Sie optional Kontingente und ein Ablaufdatum.
Secret kopieren
Nach dem Speichern wird das Secret einmalig angezeigt. Kopieren Sie es sofort und speichern Sie es in einer Umgebungsvariable. Es kann nicht erneut abgerufen werden.
Schlüsselfelder
| Feld | Beschreibung |
|---|---|
| Alias | Eindeutiges Label pro Konto. Erscheint in Logs und Dashboard-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. |
| Anfragekontingente | 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 | Gesamtlaufzeit: der Schlüssel wird dauerhaft gesperrt, sobald erreicht |
| Täglich | Letzte 24 Stunden (rollierend, nicht Mitternacht bis Mitternacht) |
| Wöchentlich | Letzte 7 Tage (rollierend) |
| Monatlich | 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 unter API-Schlüssel → Logs im Dashboard aufgezeichnet. 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 | Der Schlüssel wird sofort gesperrt und bleibt in der Liste. Schalten Sie ihn wieder ein, um ihn zu nutzen. |
| Archivieren | 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 | 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 zu Dashboard → API-Schlüssel → Neu und erstellen Sie einen neuen Schlüssel mit denselben Kategorie- und Kontingenteinstellungen. Geben Sie ihm einen neuen Alias zur Unterscheidung.
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.