--- title: REST API description: Appelez l'API client de votre installation NexCMP : authentification, référence interactive, téléchargements OpenAPI et Postman, erreurs, limites de débit et exemples curl. url: https://nexcmp.com/fr/docs/developers/api/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # REST API > **Où dans le portail :** Référence de l'API sur `https:///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 {#what-it-does} 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:///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](https://nexcmp.com/fr/docs/developers/cmp-cli/) et le [MCP server](https://nexcmp.com/fr/docs/developers/mcp/), 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 {#requirements} | É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](https://nexcmp.com/fr/docs/developers/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 {#prepare-the-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 {#connect-in-nexcmp} ### La référence interactive {#the-interactive-reference} 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 {#downloads-and-machine-readable-documents} 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`. | ```bash 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 {#authentication} Envoyez la clé dans l'en-tête `Authorization` : ```bash 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](https://nexcmp.com/fr/docs/developers/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 {#examples} ```bash # 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 {#errors} Chaque erreur est au format JSON avec un code `code` stable et un message explicite `message` : ```json {"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](https://nexcmp.com/fr/docs/billing/quotas/) 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 {#rate-limits} | 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 {#idempotency} 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 {#verify} 1. Créez une clé avec la portée `vm:read` dans le portail (**API keys › Create key**). 2. Exécutez : ```bash 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 {#limits-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 {#troubleshooting} | 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: `. | | 429 | Limite dépassée | Patientez ; utilisez `Retry-After`. | | `/apidoc` affiche moins que prévu | Module désactivé | Activez le module dans License & updates. |