--- title: REST API description: Die Kunden-API Ihrer NexCMP-Installation aufrufen: Authentifizierung, interaktive Referenz, OpenAPI- und Postman-Downloads, Fehler und curl-Beispiele. url: https://nexcmp.com/de/docs/developers/api/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # REST API > **Wo im Portal:** API-Referenz unter `https:///apidoc` (öffentlich) und API-Schlüssel unter `/api-keys`. **Wo im Admin-Bereich:** Customers › API keys (`/customers/apikeys`) listet die von Kunden erstellten Schlüssel auf. ## Funktion {#what-it-does} Jede Aktion, die ein Kunde im Portal ausführen kann — VMs auflisten und steuern, Rechnungen lesen, SSH-Schlüssel, Kubernetes, Speicher sowie Support-Tickets verwalten —, ist über eine versionierte REST API unter `https:///v1/` verfügbar. Kunden rufen sie aus Skripten und CI mit einem begrenzten **API key** auf. Dieselbe API speist das [`cmp` Befehlszeilentool](https://nexcmp.com/de/docs/developers/cmp-cli/) und den [MCP server](https://nexcmp.com/de/docs/developers/mcp/), und die Referenz wird aus der laufenden Installation generiert, sodass sie immer genau die Funktionen auflistet, die Sie eingeschaltet haben. ## Anforderungen {#requirements} | Komponente | Anforderung | |---|---| | Öffentliche HTTPS-Adresse | Die API wird auf Ihrer Hauptdomain (und auf der eigenen Domain jedes Resellers) bereitgestellt. | | Ein API-Schlüssel | Vom Kunden im Portal erstellt; siehe [API keys](https://nexcmp.com/de/docs/developers/api-keys/). | | Abhängigkeiten | Keine. Endpunkte eines Moduls, das Sie nicht aktiviert haben (zum Beispiel Kubernetes oder Object Storage), werden vor der Referenz verborgen und abgelehnt. | ## Infrastruktur vorbereiten {#prepare-the-infrastructure} Nichts zu installieren. Wenn ein Reverse-Proxy vor NexCMP sitzt, leiten Sie `/v1/`, `/mcp`, `/cli/` und `/apidoc` an das Panel weiter (die Nginx-Konfiguration des Installateurs tut dies bereits). ## In NexCMP verbinden {#connect-in-nexcmp} ### Die interaktive Referenz {#the-interactive-reference} Öffnen Sie `https://cloud.example.com/apidoc` (ersetzen Sie den Host durch Ihre Domain; Kunden eines Resellers sehen die Referenz auf der Domain des Resellers mit dessen Namen). Sie bietet Endpunkt-Dokumentation mit Anfrage- und Antwortbeispielen in curl, der `cmp` CLI, JavaScript, Python und Go, ein Suchfeld (Strg oder Cmd + K) sowie ein **Try it**-Panel. Try it sendet Anfragen nur an dieselbe Website mit einem Schlüssel, den der Besucher einfügt (wird in der Browsersitzung gespeichert); es ist standardmäßig schreibgeschützt, und Schreib- oder kostenpflichtige Aufrufe erfordern einen zusätzlichen Schalter und eine Bestätigung. ### Downloads und maschinenlesbare Dokumente {#downloads-and-machine-readable-documents} Alle sind öffentlich, benötigen keinen Schlüssel und werden pro Website generiert: | URL | Inhalt | |---|---| | `/apidoc` | Interaktive Referenz. | | `/v1/public/openapi.json` | OpenAPI 3.1-Dokument. | | `/v1/public/openapi.yaml` | Ebenso, YAML. | | `/v1/public/postman.json` | Postman-Collection. | | `/v1/public/insomnia.json` | Insomnia-Export. | | `/v1/public/api.md` | Die Referenz als eine Markdown-Datei. | | `/v1/public/api-catalog` | Light JSON: Marke, Basis-URL, Schlüsselpräfix, jeder Scope und jeder Endpunkt mit Methode, Pfad, Scope und Angabe, ob eine `Idempotency-Key` erforderlich ist. | ```bash curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40 curl -sO https://cloud.example.com/v1/public/openapi.yaml ``` Wählen Sie in Postman **Import › Link** und fügen Sie `https://cloud.example.com/v1/public/postman.json` ein. Die Referenzseite bietet zudem einteilige API-Clients für JavaScript und Python. ### Authentifizierung {#authentication} Senden Sie den Schlüssel im Header `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - Kundenschlüssel beginnen mit `vk_`. Schlüssel sind **an die Website gebunden**: Ein auf `cloud.example.com` erstellter Schlüssel funktioniert auf einer Reseller-Domain nicht. - Browser-Session-Token (`pt_...`) sind nur für das Portal bestimmt; verwenden Sie für die Automatisierung einen Schlüssel. - Die **Scopes** des Schlüssels bestimmen, welche Aufrufe er tätigen darf; ein fehlender Scope führt zu HTTP 403 `scope_required`. Siehe [API keys](https://nexcmp.com/de/docs/developers/api-keys/). - Überprüfen Sie einen Schlüssel mit `GET /v1/apikeys/self`: Dies gibt den Namen, die Scopes, das Ablaufdatum des aufrufenden Schlüssels sowie das verbleibende Kontingent des Rate-Limits zurück (jeder Schlüssel kann dies aufrufen). ### Beispiele {#examples} ```bash # List virtual machines curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX" # Start one (needs vm:write) curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \ -H "Authorization: Bearer vk_XXXX" # Create a VM (paid: needs vm:create and an Idempotency-Key) curl -s -X POST https://cloud.example.com/v1/vm \ -H "Authorization: Bearer vk_XXXX" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @vm.json ``` Entnehmen Sie die genauen Anfragefelder jeder Operation aus `/apidoc`. ### Fehler {#errors} Jeder Fehler ist JSON mit einem stabilen `code` und einer menschenlesbaren `message`: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | Typischer `code` | Bedeutung | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Fehlender oder unbekannter Schlüssel, widerrufen, abgelaufen, Aufrufer-IP außerhalb der Erlaubnisliste des Schlüssels, ein Schlüssel von einer anderen Website oder deaktivierte API-Schlüssel. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | Dem Schlüssel fehlt der Scope; der Endpunkt ist für Schlüssel nicht verfügbar; das Konto ist gesperrt; ein [quota](https://nexcmp.com/de/docs/billing/quotas/) wurde erreicht; Aktion in einer übernommenen Session nicht zulässig. | | 404 | `not_found` | Nicht gefunden — wird auch für Ressourcen zurückgegeben, die jemand anderem gehören. | | 422 | `invalid_argument` | Validierungsfehler (Feld in der Antwort benannt). | | 429 | `rate_limited` | Zu viele Anfragen; warten auf `Retry-After`. | | 503 | `maintenance` | Wartungsmodus ist aktiv: Lesevorgänge funktionieren, Schreibvorgänge werden abgelehnt. | ### Rate-Limits {#rate-limits} | Limit | Standard | |---|---| | Pro Schlüssel | 120 Anfragen pro Minute | | Pro Konto (alle Schlüssel zusammen) | 300 Anfragen pro Minute | Jede Antwort enthält `X-RateLimit-Limit`, `X-RateLimit-Remaining` und `X-RateLimit-Reset`; ein Status 429 fügt `Retry-After` hinzu. ### Idempotenz {#idempotency} Befehle, die Geld kosten oder nicht wiederholt werden können (Erstellen, Tarif wechseln, Kaufen, Löschen ...), **erfordern** einen `Idempotency-Key`-Header (beliebiger String bis zu 200 Zeichen; eine UUID eignet sich gut). Senden Sie denselben Schlüssel nach einer Zeitüberschreitung erneut, und der Server gibt das **ursprüngliche** Ergebnis zurück (mit `Idempotency-Replayed: 1`), anstatt die Operation zu wiederholen. Die Wiederverwendung eines Schlüssels für einen anderen Befehl ergibt 422; eine Anfrage, die noch verarbeitet wird, ergibt 409/`Retry-After`. Ohne den Header wird ein kostenpflichtiger Aufruf abgelehnt. ## Verifizierung {#verify} 1. Erstellen Sie im Portal einen Schlüssel mit dem Scope `vm:read` (**API keys › Create key**). 2. Führen Sie Folgendes aus: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Sie erhalten HTTP 200 und die Rate-Limit-Header. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` listet die VMs des Kontos auf. Im Portal zeigen die Spalte **Last used** des Schlüssels und das **Key usage log** die Aufrufe an. ## Limits & Hinweise {#limits-notes} - **Niemals für einen Schlüssel verfügbar:** Guthaben aufladen, abheben, Karten oder automatisches Aufladen ändern, Passwort, E-Mail oder 2FA ändern, Konto löschen, andere Schlüssel erstellen, bearbeiten oder widerrufen. Dafür ist eine angemeldete Browsersession erforderlich. - **Ausgeblendete Module:** Die Referenz und das OpenAPI-Dokument listen nur Funktionen auf, die auf dieser Website aktiviert sind. - **Antwortgröße und Paginierung:** Listenendpunkte sind paginiert (`page`, `per_page`); lesen Sie das OpenAPI-Dokument für jeden Endpunkt. - **Zeit und Geld:** Beträge sind in USD-Cents angegeben, sofern der Feldname nichts anderes besagt. - **Admin-API:** Die Admin-Konsole verfügt über eine eigene Seite **System › Admin › API** und Administrator-Schlüssel (`ofw_...`) für die Administration; diese sind von der hier beschriebenen Kunden-API getrennt. - **Versionierung:** Das Pfadpräfix `/v1` ist stabil; Antworten können neue Felder hinzugefügt werden. ## Fehlerbehebung {#troubleshooting} | Symptom | Ursache | Behebung | |---|---|---| | 401 bei neuem Schlüssel | Schlüssel von einer anderen Domain, abgelaufen oder mit Leerzeichen eingegeben | Erstellen Sie den Schlüssel auf der aufgerufenen Domain; prüfen Sie den `Authorization: Bearer vk_...`-Header. | | 403 `scope_required` | Fehlender Scope | Bearbeiten Sie den Schlüssel im Portal und fügen Sie den Scope hinzu. | | 401 `key_ip_denied` oder `site_mismatch` | Schlüssel auf andere IPs beschränkt („erlaubte IPs“) oder auf einer anderen Domain erstellt | Fügen Sie die IP Ihres Servers zu den erlaubten IPs des Schlüssels hinzu oder rufen Sie die Domain auf, auf der der Schlüssel erstellt wurde. | | 404 bei einer existierenden VM | Die VM gehört zu einem anderen Account | Verwenden Sie einen Schlüssel des Eigentümers. | | 400/422 mit der Bitte um `Idempotency-Key` | Kostenpflichtiger Vorgang ohne den Header | Fügen Sie `Idempotency-Key: ` hinzu. | | 429 | Limit überschritten | Warten Sie ab; verwenden Sie `Retry-After`. | | `/apidoc` zeigt weniger als erwartet | Modul ausgeschaltet | Aktivieren Sie das Modul unter License & updates. |