REST API

Où dans le portail : Référence de l'API sur https://<your-domain>/apidoc (public) et clés API sur /api-keys. Où dans l'admin : Customers › API keys (/customers/apikeys) liste les clés créées par les clients.

Description

Chaque action qu'un client peut effectuer dans le portail — lister et contrôler des VM, lire des factures, gérer des clés SSH, Kubernetes, du stockage, des tickets de support — est disponible via une API REST versionnée sous https://<your-domain>/v1/. Les clients l'appellent depuis des scripts et des pipelines CI avec une API key à portée limitée. La même API alimente le cmp command-line tool et le MCP server, et la référence est générée à partir de l'installation en cours d'exécution, de sorte qu'elle liste toujours exactement les fonctionnalités que vous avez activées.

Prérequis

Élément	Prérequis
Adresse HTTPS publique	L'API est hébergée sur votre domaine principal (et sur le propre domaine de chaque revendeur).
Une clé API	Créée par le client dans le portail ; voir API keys.
Dépendances	Aucun. Les points de terminaison d'un module que vous n'avez pas activé (par exemple Kubernetes ou Object Storage) sont masqués de la référence et refusés.

Préparer l'infrastructure

Rien à installer. Si un proxy inverse se trouve devant NexCMP, transférez /v1/, /mcp, /cli/ et /apidoc vers le panneau (la configuration nginx de l'installateur le fait déjà).

Connecter dans NexCMP

La référence interactive

Ouvrez https://cloud.example.com/apidoc (remplacez l'hôte par votre domaine ; les clients d'un revendeur voient la référence sur le domaine du revendeur, avec le nom du revendeur). Elle propose une documentation des points de terminaison avec des exemples de requêtes et de réponses en curl, CLI cmp, JavaScript, Python et Go, une barre de recherche (Ctrl ou Cmd + K), et un panneau Try it. Try it envoie des requêtes uniquement vers le même site, avec une clé collée par le visiteur (conservée dans la session du navigateur) ; elle est en lecture seule par défaut, et les appels payants ou d'écriture nécessitent un commutateur supplémentaire et une confirmation.

Téléchargements et documents lisibles par machine

Tous sont publics, ne nécessitent aucune clé et sont générés par site :

URL	Contenu
/apidoc	Référence interactive.
/v1/public/openapi.json	Document OpenAPI 3.1.
/v1/public/openapi.yaml	Identique, en YAML.
/v1/public/postman.json	Collection Postman.
/v1/public/insomnia.json	Exportation Insomnia.
/v1/public/api.md	La référence sous forme de fichier Markdown unique.
/v1/public/api-catalog	JSON léger : marque, URL de base, préfixe de clé, chaque portée et chaque point de terminaison avec méthode, chemin, portée et indication de la nécessité d'un Idempotency-Key.

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

Dans Postman, choisissez Import › Link et collez https://cloud.example.com/v1/public/postman.json. La page de référence propose également des clients API en un seul fichier pour JavaScript et Python.

Authentification

Envoyez la clé dans l'en-tête Authorization :

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

• Les clés client commencent par vk_. Les clés sont liées au site : une clé créée sur cloud.example.com ne fonctionne pas sur le domaine d'un revendeur.
• Les jetons de session du navigateur (pt_...) sont réservés au portail ; utilisez une clé pour l'automatisation.
• Les portées de la clé déterminent ce qu'elle peut appeler ; une portée manquante renvoie une erreur HTTP 403 scope_required. Voir API keys.
• Vérifiez une clé avec GET /v1/apikeys/self : elle renvoie le nom de la clé appelante, les portées, l'expiration et le quota de requêtes restant (toutes les clés peuvent l'appeler).

Exemples

# 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

Récupérez les champs de requête exacts de chaque opération à partir de /apidoc.

Erreurs

Chaque erreur est au format JSON avec un code code stable et un message explicite message :

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	Code code typique	Description
401	unauthenticated, key_invalid, key_revoked, key_expired, key_ip_denied, site_mismatch, api_keys_disabled	Clé manquante ou inconnue, révoquée, expirée, IP de l'appelant hors de la liste blanche de la clé, clé provenant d'un autre site, ou clés API désactivées.
403	scope_required, endpoint_not_public, account_blocked, quota_exceeded, impersonate_forbidden	La clé ne possède pas la portée requise ; le point de terminaison n'est pas accessible aux clés ; le compte est verrouillé ; un quota a été atteint ; action non autorisée dans une session usurpée.
404	not_found	Introuvable — renvoyé également pour les ressources appartenant à quelqu'un d'autre.
422	invalid_argument	Erreur de validation (champ nommé dans la réponse).
429	rate_limited	Trop de requêtes ; patientez jusqu'à Retry-After.
503	maintenance	Le mode maintenance est activé : les lectures fonctionnent, les écritures sont refusées.

Limites de taux

Limite	Valeur par défaut
Par clé	120 requêtes par minute
Par compte (toutes les clés confondues)	300 requêtes par minute

Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; un code 429 ajoute Retry-After.

Idempotence

Les commandes qui coûtent de l'argent ou ne peuvent pas être répétées (création, changement de forfait, achat, suppression ...) nécessitent un en-tête Idempotency-Key (n'importe quelle chaîne de caractères jusqu'à 200 caractères ; un UUID convient parfaitement). Renvoyez la même clé après un délai d'attente et le serveur renverra le résultat original (avec Idempotency-Replayed: 1) au lieu de répéter l'opération. Réutiliser une clé pour une commande différente renvoie 422 ; une requête encore en cours renvoie 409/Retry-After. Sans cet en-tête, un appel payant est refusé.

Vérification

1. Créez une clé avec la portée vm:read dans le portail (API keys › Create key).

2. Exécutez :

   curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

   Vous obtenez un code HTTP 200 et les en-têtes de limitation de débit.

3. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" liste les VM du compte. Dans le portail, la colonne Last used de la clé et le journal Key usage log affichent les appels.

Limites et notes

• Jamais accessibles avec une clé : recharger son solde, retirer des fonds, modifier des cartes ou le rechargement automatique, changer le mot de passe, l'e-mail ou la 2FA, supprimer le compte, créer, modifier ou révoquer d'autres clés. Ces actions nécessitent une session de navigateur connectée.
• Modules masqués : la documentation de référence et le document OpenAPI ne listent que les fonctionnalités activées sur ce site.
• Taille de réponse et pagination : les points de terminaison de liste sont paginés (page, per_page) ; consultez le document OpenAPI pour chaque point de terminaison.
• Temps et argent : les montants sont en centimes USD, sauf indication contraire dans le nom du champ.
• Admin API : la console d'administration dispose de sa propre page System › Admin › API et de clés d'administrateur (ofw_...) dédiées à l'administration ; elles sont distinctes de l'API client décrite ici.
• Versionnement : le préfixe de chemin /v1 est stable ; de nouveaux champs peuvent être ajoutés aux réponses.

Dépannage

Symptôme	Cause	Solution
401 sur une nouvelle clé	Clé provenant d'un autre domaine, expirée ou saisie avec des espaces	Créez la clé sur le domaine que vous appelez ; vérifiez l'en-tête Authorization: Bearer vk_....
403 scope_required	Portée manquante	Modifiez la clé dans le portail et ajoutez la portée.
401 key_ip_denied ou site_mismatch	Clé restreinte à d'autres IP (« allowed IPs ») ou créée sur un autre domaine	Ajoutez l'IP de votre serveur aux IP autorisées de la clé, ou appelez le domaine sur lequel la clé a été créée.
404 sur une VM existante	La VM appartient à un autre compte	Utilisez une clé du propriétaire.
400/422 demandant Idempotency-Key	Opération payante sans l'en-tête	Ajoutez Idempotency-Key: <uuid>.
429	Limite dépassée	Patientez ; utilisez Retry-After.
/apidoc affiche moins que prévu	Module désactivé	Activez le module dans License & updates.