API-Schlüssel und Scopes

Wo im Portal: API keys (/api-keys). Wo im Admin-Bereich: Customers › Customers › API keys (/customers/apikeys).

Funktion

Ein API key ermöglicht es einem Skript, einem CI-Job, der cmp CLI oder einem KI-Assistenten (MCP), die REST API im Namen eines Kunden aufzurufen – beschränkt auf die jeweils gewährten Berechtigungen (Scopes). Kundenschlüssel beginnen mit vk_. Sie können Dienste einsehen und verwalten, haben aber niemals Zugriff auf Guthaben oder das Konto selbst.

Anforderungen

Komponente	Anforderung
Kunde	Eine angemeldete Portalsitzung (ein Schlüssel kann keine anderen Schlüssel erstellen oder bearbeiten, und ein Administrator, der einen Kunden imitiert, ebenfalls nicht).
Schalter	API-Schlüssel sind standardmäßig aktiviert. Wenn sie ausgeschaltet sind, antworten Aufrufe mit 401 api_keys_disabled.
Abhängigkeiten	Die Scopes eines Produkts erscheinen nur, wenn dieses Produkt auf der Site aktiviert ist.

Schlüssel erstellen (Kunde)

1. Melden Sie sich im Portal an und öffnen Sie API keys.

2. Klicken Sie auf Create key.

3. Füllen Sie das Formular aus:

   Feld	Regel
   Key name	Erforderlich, bis zu 60 Zeichen („deploy server“, „backup script“).
   Dürfen mit diesem Key ausgeführt werden	Wählen Sie die benötigten Scopes aus – mindestens einen. Ein Nur-Lese-Schlüssel sollte keinen Schreib-Scope erhalten. Seien Sie vorsichtig mit Scopes, die Geld kosten oder Daten löschen.
   Expiry	Nie, 30 Tage, 90 Tage oder 1 Jahr (die API akzeptiert 1 bis 3650 Tage).
   Nur Aufrufe von diesen IPs zulassen	Eine IP oder ein CIDR-Bereich pro Zeile, bis zu 20 (IPv4 oder IPv6). Leer bedeutet jede IP. Pinnen Sie nach Möglichkeit die IP Ihres Servers.

4. Bestätigen Sie das Formular. Der Schlüssel wird einmal in einem Fenster mit der Aufschrift „Key created — shown ONCE“ angezeigt. Kopieren Sie ihn und klicken Sie auf I saved the key. Es wird nur ein SHA-256-Hash gespeichert, sodass selbst ein Administrator ihn nicht erneut lesen kann; wenn Sie ihn verlieren, sperren Sie ihn und erstellen Sie einen neuen.

5. Das Portal zeigt außerdem einen fertigen curl-Befehl zum Testen des Schlüssels.

Ein Schlüssel sieht aus wie vk_ gefolgt von einer langen zufälligen Zeichenfolge. Die Liste zeigt nur die ersten Zeichen (zum Beispiel vk_a1b2c3d4), die Scopes, das Ablaufdatum, die letzte Verwendung, die Anzahl der Anfragen und den Status (Active, Expired, Revoked).

Bearbeiten, sperren, prüfen

• Edit ändert Name, Scopes, erlaubte IP-Adressen und Ablaufdatum. Dies ist während einer Immatrikulationssitzung nicht zulässig.
• Revoke stoppt den Schlüssel sofort und kann nicht rückgängig gemacht werden. Die Zeile bleibt erhalten, damit das Nutzungsprotokoll verfügbar ist.
• Key usage log zeigt Schreibbefehle und jeden Fehler der letzten 60 Tage: Uhrzeit, Anfrage, Schlüssel, Ergebnis und Quell-IP.
• Ein Konto kann standardmäßig maximal 10 aktive Schlüssel halten.
• Über das CLI oder den MCP-Login erstellte Schlüssel erscheinen unter Connected apps & devices und können dort widerrufen werden.

Scopes

Scope-Namen haben die Form area:action. Welche angeboten werden, hängt von Ihren aktivierten Produkten ab.

Scope	Erlaubt
catalog:read	Pläne und den Katalog lesen.
vm:read	VMs, Metriken und VM-Rechnungen lesen.
vm:write	Power-Aktionen, kleinere Änderungen, Firewall, Schnell-Snapshots.
vm:create	VMs erstellen (kostet Geld).
vm:plan	Plan ändern oder Größe anpassen (kostet Geld).
vm:destroy	VMs löschen.
vm:restore	Eine VM aus einem Snapshot wiederherstellen (überschreibt die Festplatte).
vm:console	VNC-Konsolentickets öffnen.
sshkey:read, sshkey:write	SSH-Schlüssel lesen, hinzufügen und entfernen.
volume:read, volume:write, volume:create, volume:destroy	Datenträger (Erstellen und Vergrößern kosten Geld; Löschen führt zu Datenverlust).
backup:read, backup:write, backup:restore	Backups (Wiederherstellung überschreibt die Festplatte).
billing:read	Guthaben, Rechnungen, Zahlungsverlauf — nur lesen.
bandwidth:buy	Ein Bandbreiten-Add-on kaufen (kostet Geld).
account:read, account:write	Profil, Übersicht, Aktivität, Benachrichtigungen; account:write markiert Benachrichtigungen nur als gelesen.
apikey:read	Schlüssel des Kontos und das Nutzungsprotokoll auflisten (kann nicht erstellen, bearbeiten oder widerrufen).
apikey:self	Implizit bei jedem Schlüssel: Den aufrufenden Schlüssel inspizieren (GET /v1/apikeys/self).
ticket:read, ticket:write	Support-Tickets.
aff:read, transfer:read	Affiliate-Programm und Dienstübertragungen — nur lesen.
k8s:read, k8s:write, k8s:create, k8s:scale, k8s:destroy, k8s:kubeconfig	Kubernetes (Erstellen und Skalieren kosten Geld; kubeconfig hat Cluster-Admin-Rechte).
vpc:read, vpc:write, vpc:create, vpc:destroy	Private Cloud.
image:read, image:write	OS- und ISO-Images (Speicher wird stündlich abgerechnet).
s3:read, s3:write, s3:create, s3:destroy, s3:keys	Object Storage (das S3-Geheimnis wird einmal angezeigt).
vpn:read, vpn:detail, vpn:write, vpn:create, vpn:destroy	VPN und IPv6-Proxy (Verbindungsdetails enthalten Proxy-Passwörter).
dedicated:read, dedicated:write, dedicated:console, dedicated:create, dedicated:destroy	Dedicated Server (Bestellungen aus dem Guthaben erstellen; Löschen installiert das Betriebssystem neu).
shield:read, shield:write, shield:agent	DDoS Shield, nur wenn dieses Modul aktiviert ist.

Ein Aufruf außerhalb der Scopes des Schlüssels antwortet mit 403 scope_required; ein Pfad, den kein Schlüssel aufrufen darf, antwortet mit 403 endpoint_not_public.

Was ein Schlüssel niemals tun kann

Kein Scope öffnet: Guthaben aufladen oder abheben, Karten oder automatisches Aufladen ändern, Passwort, E-Mail oder 2FA ändern, das Konto löschen, andere Schlüssel erstellen, bearbeiten oder widerrufen. Dies erfordert immer einen angemeldeten Browser. Selbst ein kompromittierter Schlüssel kann weder das Geld noch das Konto des Kunden antasten.

Regeln, auf die Sie sich verlassen können

Regel	Detail
Seitengebunden	Ein Schlüssel funktioniert nur auf der Website (Domain), auf der er erstellt wurde.
Rate-Limits	Pro Schlüssel und pro Konto: standardmäßig 120 bzw. 300 Anfragen pro Minute.
Idempotenz	Operationen, die Geld kosten oder nicht wiederholt werden können, erfordern einen Idempotency-Key Header.
Quotas	Ein Schlüssel unterliegt denselben Quotas wie der Kunde.
Gesperrtes Konto	Die Schlüssel eines gesperrten Kunden funktionieren nicht mehr (403 account_blocked).
Audit	Der Widerruf durch einen Administrator wird in das Admin-Audit-Log geschrieben.

Administratoransicht

1. Öffnen Sie Customers › API keys (/customers/apikeys). Die Tabelle zeigt Schlüsselname und erste Zeichen, Besitzer, Scopes, Status, letzte Verwendung (Uhrzeit, Anfragemöglichkeiten, IP) und Ablaufdatum.
2. Filtern Sie nach Site, falls Sie Reseller haben. Suchen Sie nach Name, ID oder Schlüsselanfang.
3. Klicken Sie auf Revoke, um einen aktiven Schlüssel zu stoppen, oder auf Log für die Nutzungsdaten.
4. Administratoren sehen und widerrufen Schlüssel, können sie jedoch für Kunden weder lesen noch erstellen.

Verifizierung

1. Erstellen Sie einen Schlüssel mit nur dem Scope vm:read.
2. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" gibt die VM-Liste zurück.
3. curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX" antwortet mit 403 scope_required.
4. Widerrufen Sie den Schlüssel; der erste Aufruf liefert nun 401 key_revoked.

Limits & Hinweise

• Der Schlüssel wird nie wieder angezeigt. Behandeln Sie ihn wie ein Passwort und speichern Sie ihn in einem Secret-Manager oder CI-Secret.
• Bevorzugen Sie einen Schlüssel pro Skript, minimale Scopes, eine kurze Gültigkeit und eine IP-Whitelist; rotieren Sie Schlüssel, indem Sie einen neuen erstellen und den alten widerrufen.
• Schlüssel aus Geräte-Logins (CLI, MCP) sind standardmäßig 90 Tage gültig.
• Gelöschte oder übertragenen Ressourcen bleiben vom Widerruf eines Schlüssels unberührt.

Fehlerbehebung

Symptom	Ursache	Behebung
Fehler too_many_keys (422)	Das Limit aktiver Schlüssel (standardmäßig 10) ist erreicht	Widerrufen Sie einen alten Schlüssel.
Fehler invalid_argument: kein Scope ausgewählt	Kein Scope angehakt	Wählen Sie mindestens einen Scope aus.
Fehler invalid_argument bei erlaubten IPs	Ein Eintrag ist keine IP oder kein Bereich, hat eine falsche Präfixlänge oder es sind mehr als 20 Einträge	Eine IP oder CIDR pro Zeile, zum Beispiel 203.0.113.0/24.
Erstellung während der Implantation verweigert	impersonate_forbidden	Bitten Sie den Kunden, den Schlüssel zu erstellen.
401 key_expired	Ablaufdatum überschritten	Erstellen Sie einen neuen Schlüssel.
401 key_ip_denied	Aufruf-IP nicht in der Whitelist	Fügen Sie die IP hinzu oder leeren Sie die Liste.
401 api_keys_disabled	Funktion deaktiviert	Fragen Sie Ihren Administrator (Einstellung api_keys_enabled).