Autorisierung
Die Sitequest API verwendet Bearer-Token-Authentifizierung mit API-Schlüsseln.
API-Schlüssel
Erstelle API-Schlüssel in deinem Dashboard unter API / MCP (öffne dazu das Profilmenü unten in der Seitenleiste). Jeder Schlüssel kann mit einem Namen, einem Ablaufdatum und bestimmten Berechtigungen konfiguriert werden.
Füge deinen Schlüssel in jede Anfrage über den Authorization-Header ein:
Authorization: Bearer sq_live_xxxxx...
API-Schlüssel verwenden das Präfix sq_live_ gefolgt von einer 64-stelligen Hex-Zeichenkette.
Berechtigungen (Scopes)
Jedem API-Schlüssel werden ein oder mehrere Scopes zugewiesen, die den Zugriff steuern. Verwende das Prinzip der minimalen Berechtigung — vergib nur die Scopes, die deine Integration benötigt.
| Scope | Beschreibung |
|---|---|
vps:read |
Server auflisten, Status und Metriken anzeigen |
vps:files |
Dateien als root lesen und auflisten, auch darin gespeicherte Geheimnisse |
vps:manage |
Starten, Stoppen, Neustarten, ISO einlegen, Ordner anlegen, Dateien löschen |
vps:exec |
Als root Befehle ausführen, Dateien schreiben, SSH-Schlüssel hinzufügen und das Passwort zurücksetzen |
vps:scale |
CPU, RAM und Speicher bestehender Server upgraden |
vps:cancel |
Abos kündigen und Kündigungen zurücknehmen |
vps:provision |
Server erstellen und Betriebssysteme neu installieren |
domains:read |
Domains auflisten und DNS-Einträge anzeigen |
domains:manage |
DNS-Einträge und Domain-Einstellungen bearbeiten |
domains:cancel |
Domains zum Laufzeitende kündigen und Kündigungen zurücknehmen |
domains:provision |
Domains registrieren und transferieren |
webspace:read |
Webspaces auflisten, Status, Nutzung und Konfiguration anzeigen |
webspace:files |
Dateien lesen und auflisten, auch darin gespeicherte Geheimnisse |
webspace:manage |
PHP, CMS und verknüpfte Domains verwalten, Ordner anlegen, Dateien löschen |
webspace:exec |
Als Site-User Befehle ausführen, Dateien schreiben und SSH-Schlüssel hinzufügen |
webspace:scale |
Speicher und Datenbanken bestehender Webspaces upgraden |
webspace:cancel |
Abos kündigen und Kündigungen zurücknehmen |
webspace:provision |
Webspaces anlegen und kostenlose Webspaces löschen |
scale und cancel schließen read ein, aber nichts anderes. files schließt read ein, manage und exec schließen files ein. provision schließt alle anderen Scopes derselben Ressource ein, außer exec: Das Ausführen von Code muss immer ausdrücklich vergeben werden.
Wer Dateien schreiben oder SSH-Schlüssel hinterlegen kann, kann auch Code ausführen. Deshalb gehören diese Rechte zu exec. Auch files ist heikel: Damit lassen sich Passwörter und Tokens aus Konfigurationsdateien lesen.
Beim Erstellen eines Schlüssels wählst du jeden Scope einzeln und pro Ressource aus. Schlüssel mit Vollzugriff (*) lassen sich im Dashboard nicht mehr erstellen; bestehende funktionieren weiter.
Ressourcen-Beschränkungen
Zusätzlich zu Scopes kann ein API-Schlüssel auf bestimmte VPS-Instanzen, Domains und/oder Webspaces beschränkt werden. Wenn Ressourcen-Beschränkungen aktiviert sind, gilt der Schlüssel nur für die ausdrücklich erlaubten IDs — auch wenn der Scope mehr zulassen würde. Ressourcen, die mit dem Schlüssel bestellt werden, werden ihm automatisch hinzugefügt. Die Liste lässt sich nachträglich nicht bearbeiten; für den Zugriff auf weitere Ressourcen erstellst du einen neuen Schlüssel.
Ausgabenlimit
Schlüssel, die Skalieren oder Bestellen erlauben, können ein Ausgabenlimit haben. Es gilt insgesamt über die gesamte Laufzeit des Schlüssels. Upgrades zählen mit ihrer monatlichen Erhöhung, neue Bestellungen mit ihrer vollen ersten Abbuchung. Eine Domain für zehn Jahre zählt also mit dem Gesamtbetrag. Ein Kauf über dem Limit schlägt mit 403 SPENDING_LIMIT_EXCEEDED fehl, und es wird nichts abgebucht. Fehlgeschlagene Zahlungen zählen nicht. Das Limit legst du beim Erstellen des Schlüssels fest.
Läufe gruppieren
Sende den optionalen Header X-Run-Id, um zusammengehörige Aufrufe zu kennzeichnen, zum Beispiel alle Schritte eines CI-Jobs. Erlaubt sind bis zu 128 Buchstaben, Ziffern, _ und -. Im Aktivitätsprotokoll lassen sich die Einträge dann nach diesem Lauf filtern.
Rate Limiting
API-Anfragen sind auf 60 Anfragen pro Minute pro API-Schlüssel begrenzt.
Jede Antwort enthält Rate-Limit-Header:
| Header | Beschreibung |
|---|---|
X-RateLimit-Limit |
Maximale Anfragen pro Zeitfenster |
X-RateLimit-Remaining |
Verbleibende Anfragen im aktuellen Zeitfenster |
X-RateLimit-Reset |
Unix-Zeitstempel, wann das Zeitfenster zurückgesetzt wird |
Wenn das Rate-Limit überschritten wird, gibt die API 429 Too Many Requests zurück.
Fehlerantworten
Authentifizierungsfehler liefern einen JSON-Body:
{
"error": "Invalid or missing API key",
"code": "UNAUTHORIZED",
"status": 401
}
| Status | Code | Bedeutung |
|---|---|---|
| 401 | UNAUTHORIZED |
Fehlender, ungültiger, widerrufener oder abgelaufener API-Schlüssel |
| 403 | INSUFFICIENT_SCOPE |
API-Schlüssel hat nicht die erforderlichen Berechtigungen |
| 429 | RATE_LIMITED |
Zu viele Anfragen |
Sicherheitshinweise
- Committe niemals API-Schlüssel in die Versionskontrolle.
- Rotiere Schlüssel regelmäßig und widerrufe unbenutzte.
- Verwende die engsten möglichen Scopes.
- Setze ein Ablaufdatum für Schlüssel, die in CI/CD-Pipelines verwendet werden.