Admin-API-Schlüssel

Wo im Admin: System › Settings › API & AI agents (/agent/keys), Tab API keys. Dieselbe Seite enthält die Tabs Connect an AI, Connected apps und Activity.

Funktion

Ein Admin-API-Schlüssel (Präfix ak_) ermöglicht es einem KI-Client oder Skript, Ihr Panel mit genau den Berechtigungen zu verwalten, die Sie ihm erteilen. Er funktioniert für die Admin-API unter /v1/admin/ und für den Admin-MCP-Endpunkt /mcp/admin. Er funktioniert nirgendwo sonst.

Nicht dasselbe wie Kundenschlüssel

Kunden erstellen Schlüssel, die mit vk_ beginnen, im Kundenportal (API keys and scopes). Diese erreichen nur die Kunden-API und /mcp. Ein ak_-Schlüssel wird auf der Kunden-API abgelehnt und ein vk_-Schlüssel wird auf der Admin-API abgelehnt.

Anforderungen

Komponente	Anforderung
Rolle	Sie müssen im Admin angemeldet sein. Schlüssel können keine anderen Schlüssel erstellen.
Demo	Auf einem Demo-Panel ist die Seite schreibgeschützt: Es können keine Schlüssel erstellt oder widerrufen werden.
Erreichbarkeit	Der Client muss https://cloud.example.com/mcp/admin oder /v1/admin/... auf Ihrem Panel erreichen können (überprüfen Sie Ihre Firewall, wenn Sie IP-Beschränkungen verwenden).

Einen Schlüssel erstellen

1. Öffnen Sie System › Settings › API & AI agents und bleiben Sie auf dem Tab API keys.

2. Klicken Sie auf Create new key.

3. Füllen Sie das Formular aus:

   Feld	Regeln
   Name	Bis zu 60 Zeichen, zum Beispiel "Claude Code on my laptop".
   Scopes	Wählen Sie mindestens einen aus. Siehe Scopes. Beginnen Sie nur mit admin:read.
   Ablaufdatum	1, 7, 30, 60 oder 90 Tage. Standard ist 30. Maximum ist 90. Ein Schlüssel ohne Ablaufdatum kann nicht erstellt werden.
   IP-Bereiche (optional)	Eine IPv4- oder IPv6-Adresse oder ein CIDR pro Zeile, zum Beispiel 203.0.113.0/24 oder 2001:db8::/48. Höchstens 32. Leer lassen, um jede IP zuzulassen.
   Aufrufe pro Minute	1 bis 6000. Standard ist 120.

4. Klicken Sie auf Create key. Ein Dialog zeigt den Schlüssel einmalig an, zum Beispiel ak_XXXX. Kopieren Sie ihn jetzt: NexCMP speichert nur einen Hash und kann ihn nie wieder anzeigen.

5. Klicken Sie auf I have saved the key. Öffnen Sie den Tab Connect an AI, um sofort einfügbare Befehle zu erhalten, die bereits den von Ihnen erstellten Schlüssel enthalten (nur auf dieser Seite, bis Sie sie neu laden).

Scopes

Ein Schlüssel kann nur die Tools und Endpunkte verwenden, die seine Scopes erlauben. Schreib-Scopes beinhalten keinen Lesezugriff: Ein Schlüssel, der lesen und schreiben soll, benötigt zusätzlich admin:read.

Scope	Was er erlaubt
admin:read	Einstellungen, Katalog, Kunden, Abrechnung und Protokolle lesen. Geheimnisse werden niemals zurückgegeben.
catalog:write	Tarife, Betriebssystem-Templates, Kontingente, Rabattcodes.
infra:write	Infrastrukturquellen (CloudStack, Proxmox), Zonen, Server.
billing:write	Zahlungsgateways, Währung, Rechnungen, Guthaben. Geldtransaktionen erfordern eine Bestätigung.
customers:write	Kunden und Reseller.
settings:write	Allgemeine Einstellungen, Branding, E-Mail, rechtliche Seiten, Module, Benachrichtigungen.
ai:write	Der KI-Anbieter und KI-Funktionen.
secrets:write	Schreiben von Passwörtern und API-Schlüsseln. Sie können gesetzt, aber niemals ausgelesen werden.

Das Festlegen eines Geheimnisses erfordert zwei Scopes

Jeder Aufruf, der ein Passwort, einen API-Schlüssel oder einen Token-Wert enthält (ein SMTP-Passwort, einen Zahlungsschlüssel, ein Telegram-Bot-Token, einen KI-Anbieter-Schlüssel, CloudStack- oder Proxmox-Anmeldeinformationen), benötigt secrets:write und den Scope des Bereichs (zum Beispiel settings:write für SMTP). Wenn Sie Geheimnisse lieber selbst eingeben möchten, lassen Sie secrets:write weg und tragen Sie diese im Admin-Bereich ein.

Einen Schlüssel widerrufen

1. Finden Sie den Schlüssel in der Tabelle (Status Active, Expired oder Revoked; Last used zeigt den Zeitpunkt und den Client).
2. Klicken Sie auf Revoke und bestätigen Sie.

Der Schlüssel funktioniert sofort nicht mehr. Das Widerrufen ist endgültig; erstellen Sie einen neuen Schlüssel, wenn Sie erneut einen benötigen.

Was ein Schlüssel niemals tun kann

Ein Schlüssel kann diese Bereiche niemals erreichen, unabhängig von seinen Scopes. Dafür müssen Sie im Admin-Bereich angemeldet sein.

• Administratoren erstellen oder ändern, 2FA und Anmeldesicherheit, Admin-Sitzungen sowie die Admin-API-Token.
• Admin-Schlüssel, OAuth-Verbindungen und KI-Konten erstellen, auflisten oder widerrufen oder die KI-Konsole verwenden.
• Das Panel sichern oder wiederherstellen, aktualisieren oder seine Lizenz ändern.
• Als Kunde oder Reseller anmelden, die Konsole eines Kunden öffnen, VM-Zugangsdaten oder Kubeconfig lesen, SSH-Schlüssel setzen oder Passwörter senden beziehungsweise zurücksetzen.
• Netzwerk- und Routing-Module ändern (BGP, FRR, RTBH, XDP, Schnittstellen, statische und Richtlinien-Routen, NAT) oder externe Agenten sowie Portal-Integrationen. Diese sind schreibgeschützt.
• Einstellungen wie demo_*, admin_*, Host-Listen, Passkey, Re-Authentifizierung und Captcha-Geheimnisse ändern.

Alles, was nicht durch eine Regel abgedeckt ist, ist standardmäßig für Schreibvorgänge geschlossen und für Lesevorgänge mit admin:read lesbar.

Aktionen, die Ihre Bestätigung erfordern

Diese werden erst nach Bestätigung einer Vorschau ausgeführt (siehe Two-step confirmation):

• Ändern eines Kunden-Guthabens oder Reseller-Wallets, Auszahlen von Geldern, Abrechnungsdatensätze, der Wechselkurs.
• Ändern von Preisen (Tarifpreise, Massenerstellung von Tarifen, Image- und Speicherpreise) sowie Erstellen von Rabatt- oder Guthaben-Codes.
• Speichern von Zahlungs-Gateway-Zugangsdaten oder der CloudStack-Verbindung.
• Löschen von Inhalten, Sperren oder Löschen eines Kunden, Ändern von Kundenlimits, Aussetzen oder Schließen eines Resellers.
• Aktionen auf Kundenservern oder Erstellen eines kostenpflichtigen Servers für einen Kunden.
• Ändern von seitenweiten Schaltern, Anmeldesicherheitseinstellungen oder Zahlungseinstellungen über die allgemeinen Einstellungen.

Zweistufige Bestätigung

Wenn ein Aufruf eine Bestätigung erfordert, ändert sich zunächst nichts. Die Antwort lautet HTTP 428 mit confirm_required, einer confirm_token, einem preview (Methode, Pfad, Grund, die neuen Werte und, falls verfügbar, die aktuellen Werte) und expires_in: 300.

1. Der Client zeigt Ihnen die Vorschau.
2. Nach der Freigabe wird dieselbe gleiche Anfrage (gleiche Methode, gleicher Pfad und Body) mit dem Header X-Confirm-Token: <confirm_token> wiederholt. MCP-Tools verwenden stattdessen das Argument confirm_token.
3. Das Token funktioniert einmalig und läuft nach 5 Minuten ab.

Schlüssel, die im Admin-Bereich für AI Chat erstellt wurden, können nur auf dem Bildschirm bestätigt werden: Die Antwort gibt confirm_in: "ui" aus und im Admin-Bereich erscheint eine Bestätigungskarte. Die KI kann dies nicht genehmigen.

Rate Limit und IP-Regeln

• Überschreitet ein Aufruf das Minutenlimit, wird rate_limited (HTTP 429) mit Retry-After: 60 zurückgegeben.
• Bei festgelegten IP-Bereichen geben Anfragen von anderen Adressen ip_not_allowed (HTTP 403) zurück.

Aktivitätsprotokoll

Der Activity-Tab listet alle mit einem Key getätigten Aufrufe auf, beginnend mit den neuesten: Zeitpunkt, Key, Client, Herkunft (http, mcp, chat, cli, confirm, preview), Methode und Pfad, Tool, HTTP-Status, IP und die (maskierten) Details. Sie können nach Pfad, Tool oder Key-Name suchen, nur Fehler (HTTP 400 und höher) oder nur auf Bestätigung wartende Aufrufe (428 und höher) anzeigen und den Zeitraum auf die letzte Stunde, 24 Stunden oder 7 Tage beschränken. NexCMP speichert die letzten 200,000 Einträge. Über einen Key vorgenommene Änderungen erscheinen zudem unter Logs › Admin actions unter dem Namen ak:<admin>/<key name>.

Verifizierung

Testen Sie einen Read-only-Schlüssel von einem beliebigen Computer innerhalb des IP-Bereichs:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

Sie erhalten eine JSON-Liste der Tools, die Ihre Scopes erlauben. Führen Sie eines aus:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

Die Zeit unter Last used des Schlüssels aktualisiert sich und der Aufruf erscheint in Activity. Die vollständige Tool-Liste und eine OpenAPI-Beschreibung (/v1/admin/openapi.json) werden unter Connect an AI client beschrieben.

Fehler

Fehler sind im JSON-Format: {"error": {"code": "...", "message": "..."}}.

HTTP	code	Bedeutung	Behebung
401	invalid_key	Der Schlüssel fehlt, ist fehlerhaft oder unbekannt. Wird auch zurückgegeben, wenn ein ak_-Schlüssel auf einem Nicht-Admin-Pfad verwendet wird.	Prüfen Sie den Schlüssel; verwenden Sie ihn nur auf /v1/admin/ und /mcp/admin.
401	key_expired	Die Gültigkeit des Schlüssels ist abgelaufen.	Erstellen Sie einen neuen Schlüssel.
401	key_revoked	Der Schlüssel wurde widerrufen.	Erstellen Sie einen neuen Schlüssel.
403	ip_not_allowed	Die IP des Aufrufers liegt außerhalb der IP-Bereiche des Schlüssels.	Rufen Sie von einer erlaubten IP aus an oder erstellen Sie einen Schlüssel mit dem entsprechenden Bereich.
403	local_only_key	Ein für AI Chat oder das Server-CLI erstellter Schlüssel wurde von einem anderen Computer aus verwendet.	Diese Schlüssel funktionieren nur direkt auf dem Panel-Server.
403	insufficient_scope	Dem Schlüssel fehlt ein Scope; die Antwort enthält required_scope.	Erstellen Sie einen Schlüssel mit diesem Scope.
403	forbidden_for_keys	Der Endpunkt oder die Einstellung, die Sie ändern wollten, ist für Schlüssel gesperrt.	Führen Sie dies im Admin-Bereich aus.
403	demo_read_only	Das Panel befindet sich im Demomodus und der Aufruf führt Schreibvorgänge aus.	Verwenden Sie ein Panel, das sich nicht im Demomodus befindet.
403	confirm_in_ui	Diese Aktion muss im Admin-Bereich auf dem Bildschirm bestätigt werden.	Genehmigen Sie die Bestätigungskarte.
428	confirm_required	Eine Vorschau ist bereit; es wurde nichts geändert. Enthält confirm_token.	Zeigen Sie die Vorschau an und wiederholen Sie den Vorgang dann mit X-Confirm-Token.
409	confirm_expired	Das Token ist älter als 5 Minuten.	Senden Sie die Anfrage für eine neue Vorschau erneut.
409	confirm_mismatch	Das Token gehört zu einer anderen Anfrage (Methode, Pfad oder Body weichen ab).	Wiederholen Sie die identische Anfrage.
409	confirm_invalid	Unbekanntes oder bereits verwendetes Token.	Senden Sie die Anfrage für eine neue Vorschau erneut.
429	rate_limited	Zu viele Aufrufe in dieser Minute.	Warten Sie auf Retry-After.
400	invalid_path	Der Pfad enthält unzulässige Sequenzen.	Verwenden Sie einen einfachen Pfad.
413	too_large	Der Body ist größer als 10 MB.	Senden Sie weniger Daten.
400	invalid_argument	Ein Tool-Argument fehlt, ist unbekannt oder hat den falschen Typ; die Nachricht benennt es.	Beheben Sie das Argument.

Limits & Hinweise

• Halten Sie Schlüssel kurzlebig und beschränkt. Bevorzugen Sie einen Schlüssel pro Client, damit Sie einzelne widerrufen können.
• Ein Schlüssel ist so mächtig wie seine Scopes. secrets:write plus billing:write ist die sensibelste Kombination; finanzbezogene Aktionen stoppen weiterhin bei einer Vorschau.
• Automatisch erstellte Schlüssel (für AI Chat, das Server-CLI) sind nur wenige Minuten gültig und funktionieren ausschließlich vom Panel-Server aus.
• Um einen KI-Client sofort zu trennen, widerrufen Sie seinen Schlüssel. OAuth-Verbindungen werden auf dem Tab Connected apps (OAuth connectors) widerrufen.