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 Rate Limit Exceeded mit dem Kontingentnamen in der Meldung zurück:
{ "error": "Rate limit exceeded: quota total" }{ "error": "Rate limit exceeded: quota daily" }{ "error": "Rate limit exceeded: quota weekly" }{ "error": "Rate limit exceeded: quota monthly" }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). Planlimits geben 429 Too Many Requests zurück. 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 vs. Löschen
| Aktion | Auswirkung |
|---|---|
| Deaktivieren | Schlüssel wird sofort gesperrt. Nutzungsverlauf und Einstellungen bleiben erhalten. Kann reaktiviert werden. |
| Löschen | Entfernt den Schlüssel und seine Konfiguration dauerhaft. Nur möglich, wenn der Schlüssel noch nie verwendet wurde. |
Bevorzugen Sie Deaktivierung gegenüber Löschung. Wenn ein Schlüssel einen Anfrageverlauf hat, kann er nicht gelöscht werden. Der Verlauf wird für Abrechnung und Audits aufbewahrt.
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 im Dashboard auf inaktiv. 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: quota … | 401 | Rollierendes Schlüsselkontingent erreicht |
exceeded the … rate limit on your subscription | 429 | 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.