---
title: API-Schlüssel und Scopes
description: Wie Kunden API-Schlüssel erstellen (vk_-Präfix), Scopes auswählen, nach IP und Ablauf limitieren und wie Administratoren sie prüfen und sperren.
url: https://nexcmp.com/de/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# API-Schlüssel und Scopes {#api-keys-and-scopes}

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

## Funktion {#what-it-does}

Ein **API key** ermöglicht es einem Skript, einem CI-Job, der [`cmp` CLI](https://nexcmp.com/de/docs/developers/cmp-cli/) oder einem KI-Assistenten ([MCP](https://nexcmp.com/de/docs/developers/mcp/)), die [REST API](https://nexcmp.com/de/docs/developers/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 {#requirements}

| 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) {#create-a-key-customer}

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-revoke-audit}

- **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 {#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 {#what-a-key-can-never-do}

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 {#rules-you-can-rely-on}

| 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](https://nexcmp.com/de/docs/billing/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 {#administrator-view}

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.

![Administratorliste der Kunden-API-Schlüssel mit Scopes, Status, letzter Verwendung und Widerrufen-Schaltfläche](https://nexcmp.com/de/docs/images/developers/api-keys-02-admin.webp)

## Verifizierung {#verify}

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 {#limits-notes}

- 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 {#troubleshooting}

| 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`). |