API-Schlüssel
API-Schlüssel
API-Schlüssel (Präfix wgk_) gewähren programmatischen Zugriff auf Ihr Konto: CLI, VS Code-Erweiterung, CI-Skripte, oder direkte Aufrufe der API.
Einen Schlüssel erstellen
Dashboard → Entwickler → API-Schlüssel → Neuer Schlüssel:
| Einstellung | Rolle |
|---|---|
| Name | Zur Wiedererkennung („CI Produktion", „privater Laptop"…) |
| Scopes | Was der Schlüssel tun darf (siehe unten) |
| Ratenlimit | Erlaubte Anfragen/Minute (60 standardmäßig) |
| Ablauf | Optional, empfohlen für CI-Schlüssel |
Der vollständige Schlüssel wird nur einmal angezeigt, bei der Erstellung. Speichern Sie ihn in einem Secret-Manager; danach bleibt nur seine gekürzte Signatur sichtbar.
Die Scopes
Ein Scope folgt dem Format ressource:aktion:
projects:read # Projekte auflisten und lesen
services:write # deployen, neu starten, konfigurieren
services:* # alles zu Diensten
billing:read # Rechnungen und Abonnement lesen
* # alle Rechte (außerhalb von Tests zu vermeiden)
Prinzip des geringsten Privilegs: ein CI-Schlüssel, der nur deployt, braucht nur services:write. Ein Monitoring-Schlüssel, projects:read. Erstellen Sie mehrere enge Schlüssel statt eines einzigen breiten.
Einen Schlüssel verwenden
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
Ein Schlüssel agiert im Namen seines Besitzers: er erbt Ihre Rollen auf jedem Projekt, niemals mehr. Seine Scopes können nur einschränken, nicht erweitern.
Für einen Unterkunden agieren (Reseller)
Ein mit aktiviertem Für Unterkunden agieren erstellter Schlüssel (vorbehalten dem Eigentümer einer Organisation) kann im Namen eines seiner Unterkunden agieren, indem der Header X-Act-As-User-Id hinzugefügt wird:
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx" \
-H "X-Act-As-User-Id: usr_des_unterkunden"
Der Ziel-Unterkunde muss derselben Organisation angehören, sonst schlägt die Anfrage fehl, als ob die Ressource nicht existierte (404). Die Scopes des Schlüssels gelten weiterhin. Für einen Unterkunden zu agieren gewährt keine Rechte über die des Schlüssels hinaus.
Audit-Protokoll
Jeder Schlüssel hat sein eigenes Protokoll, einsehbar unter Dashboard → Entwickler → API-Schlüssel → Protokoll-Symbol, oder über GET /api/v1/api-keys/:id/audit-log: die letzten 100 Aufrufe (Methode, Pfad, Rückgabecode, Dauer, und ob die Anfrage für einen Unterkunden erfolgte). Nützlich, um einen leckenden Schlüssel oder ein still fehlschlagendes Skript zu erkennen.
Limits
- WebSockets ausgeschlossen: Echtzeit-Streams (Live-Logs, Zusammenarbeit) erfordern eine Browser-Session: Ein API-Schlüssel kann sich nicht damit verbinden. Der REST-Snapshot der Logs bleibt zugänglich.
- Ein abgelaufener oder widerrufener Schlüssel wird sofort abgelehnt; widerrufen Sie ohne zu zögern jeden potenziell exponierten Schlüssel (der Widerruf ist sofort und wirkt sich nicht auf Ihre anderen Schlüssel aus).
- Jeder Schlüssel hat sein eigenes Ratenlimit: Ein außer Kontrolle geratenes Skript erschöpft nicht das Kontingent der anderen.