--- title: Admin-API-Schlüssel description: Erstellen und widerrufen Sie ak_ Admin-Keys für AI Agents: die acht Bereiche, Ablauf, IP-Bereiche, Rate Limit und alle Fehlercodes. url: https://nexcmp.com/de/docs/configure-with-ai/admin-api-keys/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Admin-API-Schlüssel {#admin-api-keys} > **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 {#what-it-does} 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. ::: info Nicht dasselbe wie Kundenschlüssel Kunden erstellen Schlüssel, die mit `vk_` beginnen, im Kundenportal ([API keys and scopes](https://nexcmp.com/de/docs/developers/api-keys/)). 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 {#requirements} | 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 {#create-a-key} 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](#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). ![Dialog für neuen Schlüssel mit ausgefülltem Namen, Scope-Kontrollkästchen, Ablaufdatum und IP-Bereich](https://nexcmp.com/de/docs/images/configure-with-ai/admin-api-keys-01-create.webp) ![Dialog, der den neuen Schlüssel einmalig mit einer Kopierschaltfläche und einer Warnung anzeigt](https://nexcmp.com/de/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp) ## Scopes {#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. | ::: tip 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 {#revoke-a-key} 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 {#what-a-key-can-never-do} 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 {#actions-that-need-your-confirmation} Diese werden erst nach Bestätigung einer Vorschau ausgeführt (siehe [Two-step confirmation](#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 {#two-step-confirmation} 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: ` 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 {#rate-limit-and-ip-rules} - Ü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 {#activity-log} 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:/`. ![Aktivitäts-Tab mit Auflistung von Aufrufen nach Status, Client, Tool und IP](https://nexcmp.com/de/docs/images/configure-with-ai/admin-api-keys-03-activity.webp) ## Verifizierung {#verify} Testen Sie einen Read-only-Schlüssel von einem beliebigen Computer innerhalb des IP-Bereichs: ```bash 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: ```bash 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](https://nexcmp.com/de/docs/configure-with-ai/mcp-admin/) beschrieben. ## Fehler {#errors} 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 {#limits-notes} - 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](https://nexcmp.com/de/docs/configure-with-ai/oauth-connectors/)) widerrufen.