API-Dokumentation

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.