Clés API administrateur

Où dans l'admin : System › Settings › API & AI agents (/agent/keys), onglet API keys. La même page contient les onglets Connect an AI, Connected apps et Activity.

Description

Une clé API administrateur (préfixe ak_) permet à un client IA ou à un script de gérer votre panneau avec exactement les permissions que vous lui accordez. Elle fonctionne sur l'API admin sous /v1/admin/ et sur le point de terminaison MCP admin /mcp/admin. Elle ne fonctionne nulle part ailleurs.

Différent des clés client

Les clients créent des clés commençant par vk_ dans le portail client (API keys and scopes). Celles-ci n'accèdent qu'à l'API client et à /mcp. Une clé ak_ est refusée sur l'API client, et une clé vk_ est refusée sur l'API admin.

Prérequis

Élément	Prérequis
Rôle	Vous devez être connecté en tant qu'administrateur. Les clés ne peuvent pas créer d'autres clés.
Démo	Sur un panneau de démonstration, la page est en lecture seule : aucune clé ne peut être créée ou révoquée.
Accessibilité	Le client doit pouvoir joindre https://cloud.example.com/mcp/admin ou /v1/admin/... sur votre panneau (vérifiez votre pare-feu si vous utilisez des restrictions IP).

Créer une clé

1. Ouvrez System › Settings › API & AI agents et restez sur l'onglet API keys.

2. Cliquez sur Create new key.

3. Remplissez le formulaire :

   Champ	Règles
   Name	Jusqu'à 60 caractères, par exemple "Claude Code on my laptop".
   Portées	Cochez-en au moins une. Voir Scopes. Commencez par admin:read uniquement.
   Expiration	1, 7, 30, 60 ou 90 jours. Par défaut 30. Maximum 90. Une clé sans date d'expiration ne peut pas être créée.
   Plages IP (optionnel)	Une adresse IPv4 ou IPv6 ou un CIDR par ligne, par exemple 203.0.113.0/24 ou 2001:db8::/48. Au maximum 32. Laissez vide pour autoriser n'importe quelle IP.
   Appels par minute	1 à 6000. Par défaut 120.

4. Cliquez sur Create key. Une boîte affiche la clé une seule fois, par exemple ak_XXXX. Copiez-la maintenant : NexCMP ne stocke qu'un hachage et ne pourra plus jamais l'afficher.

5. Cliquez sur I have saved the key. Ouvrez l'onglet Connect an AI pour obtenir des commandes prêtes à coller contenant déjà la clé que vous venez de créer (uniquement sur cette page, jusqu'à son rechargement).

Portées

Une clé ne peut utiliser que les outils et points de terminaison autorisés par ses périmètres. Les périmètres d'écriture n'incluent pas l'accès en lecture : une clé devant lire et écrire a également besoin de admin:read.

Portée	Ce qu'elle autorise
admin:read	Lire les paramètres, le catalogue, les clients, la facturation et les journaux. Les secrets ne sont jamais renvoyés.
catalog:write	Forfaits, modèles d'OS, quotas, codes de réduction.
infra:write	Sources d'infrastructure (CloudStack, Proxmox), zones, serveurs.
billing:write	Passerelles de paiement, devise, factures, soldes. Les actions financières nécessitent une confirmation.
customers:write	Clients et revendeurs.
settings:write	Paramètres généraux, image de marque, e-mails, pages légales, modules, notifications.
ai:write	Le fournisseur d'IA et les fonctionnalités d'IA.
secrets:write	Écrire des mots de passe et des clés API. Ils peuvent être définis mais jamais relus.

La définition d'un secret nécessite deux portées

Tout appel contenant un mot de passe, une clé API ou un jeton (mot de passe SMTP, clé de paiement, jeton de bot Telegram, clé de fournisseur d'IA, identifiants CloudStack ou Proxmox) nécessite secrets:write ainsi que la portée du domaine (par exemple settings:write pour le SMTP). Si vous préférez saisir les secrets vous-même, omettez secrets:write et saisissez-les dans l'administration.

Révoquer une clé

1. Recherchez la clé dans le tableau (statut Active, Expired ou Revoked ; Last used indique l'heure et le client).
2. Cliquez sur Revoke et confirmez.

La clé cesse de fonctionner immédiatement. La révocabilité est définitive ; créez une nouvelle clé si vous en avez nouveau besoin.

Ce qu'une clé ne peut jamais faire

Une clé ne peut jamais atteindre ces zones, quelles que soient ses portées. Celles-ci exigent que vous soyez connecté en tant qu'administrateur.

• Créer ou modifier des utilisateurs administrateurs, la 2FA et la sécurité des connexions, les sessions admin et les jetons API admin.
• Créer, lister ou révoquer des clés admin, des connexions OAuth et des comptes d'IA, ou utiliser la console d'IA.
• Sauvegarder ou restaurer le panneau, le mettre à jour ou modifier sa licence.
• Se connecter en tant que client ou revendeur, ouvrir la console d'un client, lire les identifiants de VM ou le fichier kubeconfig, définir des clés SSH, ou envoyer/réinitialiser des mots de passe.
• Modifier les modules de réseau et de routage (BGP, FRR, RTBH, XDP, interfaces, routes statiques et de stratégie, NAT) ou les agents externes et l'intégration du portail. Ceux-ci sont en lecture seule.
• Modifier des paramètres tels que demo_*, admin_*, les listes d'hôtes, les passkeys, la ré-authentification et les secrets CAPTCHA.

Tout ce qui n'est pas couvert par une règle est fermé par défaut en écriture, et accessible en lecture avec admin:read.

Actions nécessitant votre confirmation

Celles-ci n'aboutissent qu'après validation d'un aperçu (voir Two-step confirmation) :

• Modifier le solde d'un client ou le portefeuille d'un revendeur, effectuer un versement, enregistrer la facturation ou modifier le taux de change.
• Modifier les prix (tarifs des offres, création en masse d'offres, tarification des images et du stockage) et créer des codes de réduction ou de montant.
• Enregistrer les identifiants d'une passerelle de paiement ou la connexion CloudStack.
• Supprimer un élément, bloquer ou supprimer un client, modifier les limites d'un client, suspendre ou clôturer un revendeur.
• Interagir avec les serveurs clients ou créer un serveur payant pour un client.
• Modifier les commutateurs globaux du site, les paramètres de sécurité des connexions ou les options de paiement via les paramètres généraux.

Confirmation en deux étapes

Lorsqu'un appel nécessite une confirmation, rien n'est encore modifié. La réponse est un code HTTP 428 accompagné de confirm_required, d'un confirm_token, d'un preview (méthode, chemin, motif, nouvelles valeurs et, le cas échéant, valeurs actuelles) et de expires_in: 300.

1. Le client affiche l'aperçu.
2. Après votre approbation, il répète la même requête (même méthode, chemin et corps) avec l'en-tête X-Confirm-Token: <confirm_token>. Les outils MCP prennent l'argument confirm_token à la place.
3. Le jeton est à usage unique et expire au bout de 5 minutes.

Les clés créées dans l'administration pour l'AI Chat ne peuvent être confirmées que visuellement : la réponse indique confirm_in: "ui" et une carte de confirmation apparaît dans l'administration. L'IA ne peut pas l'approuver.

Limitation de débit et règles IP

• Au-delà de la limite par minute, un appel renvoie rate_limited (HTTP 429) avec Retry-After: 60.
• Si des plages IP sont définies, les appels provenant de toute autre adresse renvoient ip_not_allowed (HTTP 403).

Journal d'activité

L'onglet Activity répertorie chaque appel effectué avec une clé, du plus récent au plus ancien : heure, clé, client, mode d'arrivée (http, mcp, chat, cli, confirm, preview), méthode et chemin, outil, statut HTTP, IP et détails (masqués). Vous pouvez effectuer une recherche par chemin, outil ou nom de clé, n'afficher que les erreurs (HTTP 400 et supérieur) ou uniquement les appels en attente de confirmation (428 et supérieur), et limiter la période à la dernière heure, aux 24 derniers jours ou aux 7 derniers jours. NexCMP conserve les 200,000 derniers enregistrements. Les modifications effectuées via une clé apparaissent également dans Logs › Admin actions sous le nom ak:<admin>/<key name>.

Vérification

Testez une clé en lecture seule depuis n'importe quelle machine située dans la plage IP :

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

Vous obtenez une liste JSON des outils autorisés par vos périmètres. Exécutez-en un :

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 '{}'

L'heure de Last used de la clé est actualisée et l'appel apparaît dans Activity. La liste complète des outils et une description OpenAPI (/v1/admin/openapi.json) sont présentées dans Connect an AI client.

Erreurs

Les erreurs sont au format JSON : {"error": {"code": "...", "message": "..."}}.

HTTP	code	Description	Solution
401	invalid_key	La clé est absente, malformée ou inconnue. Également renvoyé lorsqu'une clé ak_ est utilisée sur un chemin non administrateur.	Vérifiez la clé ; utilisez-la uniquement sur /v1/admin/ et /mcp/admin.
401	key_expired	La date d'expiration de la clé est dépassée.	Créez une nouvelle clé.
401	key_revoked	La clé a été révoquée.	Créez une nouvelle clé.
403	ip_not_allowed	L'adresse IP de l'appelant se trouve en dehors des plages IP de la clé.	Effectuez l'appel à partir d'une IP autorisée ou créez une clé avec la plage appropriée.
403	local_only_key	Une clé créée pour AI Chat ou le CLI du serveur a été utilisée depuis une autre machine.	Ces clés ne fonctionnent que sur le serveur du panneau lui-même.
403	insufficient_scope	La clé ne possède pas de périmètre ; la réponse inclut required_scope.	Créez une clé disposant de ce périmètre.
403	forbidden_for_keys	L'endpoint, ou le paramètre que vous avez tenté de modifier, n'est pas accessible aux clés.	Effectuez cette action dans l'administration.
403	demo_read_only	Le panneau est en mode démonstration et l'appel effectue une écriture.	Utilisez un panneau qui n'est pas en mode démonstration.
403	confirm_in_ui	Cette action doit être confirmée à l'écran dans l'administration.	Approuvez la carte de confirmation.
428	confirm_required	Un aperçu est prêt ; rien n'a été modifié. Inclut confirm_token.	Affichez l'aperçu, puis réitérez avec X-Confirm-Token.
409	confirm_expired	Le jeton date de plus de 5 minutes.	Envoyez à nouveau la requête pour obtenir un nouvel aperçu.
409	confirm_mismatch	Le jeton appartient à une autre requête (la méthode, le chemin ou le corps diffèrent).	Répétez la requête à l'identique.
409	confirm_invalid	Jeton inconnu ou déjà utilisé.	Envoyez à nouveau la requête pour obtenir un nouvel aperçu.
429	rate_limited	Trop d'appels au cours de cette minute.	Attendre Retry-After.
400	invalid_path	Le chemin contient des séquences interdites.	Utilisez un chemin simple.
413	too_large	Le corps de la requête dépasse 10 Mo.	Envoyez moins de données.
400	invalid_argument	Un argument d'outil est manquant, inconnu ou d'un type incorrect ; le message le nomme explicitement.	Corrigez l'argument.

Limites et notes

• Maintenez la durée de vie des clés courte et limitez leurs périmètres. Préférez une clé par client afin de pouvoir en révoquer une seule.
• Une clé a autant de pouvoir que ses périmètres. secrets:write associé à billing:write constitue la combinaison la plus sensible ; les actions financières s'arrêtent toujours à un aperçu.
• Les clés générées automatiquement (pour AI Chat, le CLI du serveur) n'ont une durée de vie que de quelques minutes et ne fonctionnent qu'à partir du serveur du panneau.
• Pour couper un client IA immédiatement, révoquez sa clé. Les connexions OAuth sont révoquées sur l'onglet Connected apps (OAuth connectors).