Clés API et portées

Où dans le portail : API keys (/api-keys). Où dans l'administration : Customers › Customers › API keys (/customers/apikeys).

Description

Une API key permet à un script, à un job CI, au cmp CLI ou à un assistant IA (MCP) d'appeler la REST API au nom d'un client, avec uniquement les autorisations (scopes) qui lui ont été accordées. Les clés client commencent par vk_. Elles peuvent lire et gérer les services, mais ne peuvent jamais toucher à l'argent ou au compte lui-même.

Prérequis

Élément	Prérequis
Client	Une session de portail active (une clé ne peut ni créer ni modifier d'autres clés, et un administrateur usurpant l'identité d'un client ne le peut pas non plus).
Bouton	Les clés API sont activées par défaut. Si elles sont désactivées, les appels renvoient 401 api_keys_disabled.
Dépendances	Les scopes d'un produit n'apparaissent que lorsque ce produit est activé sur le site.

Créer une clé (client)

1. Connectez-vous au portail et ouvrez API keys.

2. Cliquez sur Create key.

3. Remplissez le formulaire :

   Champ	Règle
   Key name	Obligatoire, jusqu'à 60 caractères ("deploy server", "backup script").
   Ce que cette clé peut faire	Cochez les scopes dont vous avez besoin — au moins un. Une clé en lecture seule ne doit obtenir aucun scope d'écriture. Soyez prudent avec les scopes qui coûtent de l'argent ou suppriment des données.
   Expiry	Jamais, 30 jours, 90 jours ou 1 an (l'API accepte de 1 à 3650 jours).
   N'autoriser les appels que depuis ces IP	Une adresse IP ou une plage CIDR par ligne, jusqu'à 20 (IPv4 ou IPv6). Vide signifie n'importe quelle IP. Épinglez l'IP de votre serveur dès que possible.

4. Confirmez le formulaire. La clé s'affiche une seule fois dans une fenêtre "Key created — shown ONCE". Copiez-la et cliquez sur I saved the key. Seul un hachage SHA-256 est stocké, de sorte qu'même un administrateur ne peut plus la lire ; si vous la perdez, révoquez-la et créez-en une nouvelle.

5. Le portail affiche également une curl commande prête à l'emploi pour tester la clé.

Une clé se présente sous la forme vk_ suivie d'une longue chaîne aléatoire. La liste n'affiche que les premiers caractères (par exemple vk_a1b2c3d4), les scopes, l'expiration, la dernière utilisation, le nombre de requêtes et le statut (Active, Expired, Revoked).

Modifier, révoquer, auditer

• Edit modifie le nom, les portées, les adresses IP autorisées et l'expiration. Cette action n'est pas autorisée lors d'une session usurpée.
• Revoke désactive immédiatement la clé et cette action est irréversible. La ligne est conservée afin que le journal d'utilisation reste disponible.
• Key usage log affiche les commandes d'écriture et toutes les erreurs des 60 derniers jours : heure, requête, clé, résultat et adresse IP source.
• Un compte peut détenir au maximum 10 clés actives par défaut.
• Les clés créées via la CLI ou la connexion MCP apparaissent sous Connected apps & devices et peuvent y être révoquées.

Portées

Les noms de portées ont le format area:action. Celles qui sont proposées dépendent des produits que vous avez activés.

Portée	Autorise
catalog:read	Lecture des plans et du catalogue.
vm:read	Lecture des VMs, des métriques et des factures de VM.
vm:write	Actions d'alimentation, modifications mineures, pare-feu, instantanés rapides.
vm:create	Création de VMs (payant).
vm:plan	Modification du plan ou redimensionnement (payant).
vm:destroy	Suppression de VMs.
vm:restore	Restauration d'une VM à partir d'un instantané (écrase le disque).
vm:console	Ouverture de tickets pour la console VNC.
sshkey:read, sshkey:write	Lecture, ajout et suppression de clés SSH.
volume:read, volume:write, volume:create, volume:destroy	Volumes de données (la création et l'agrandissement sont payants ; la suppression entraîne la perte des données).
backup:read, backup:write, backup:restore	Backups (la restauration écrase le disque).
billing:read	Portefeuille, factures, historique des paiements — lecture seule.
bandwidth:buy	Achat d'une option de bande passante supplémentaire (payant).
account:read, account:write	Profil, aperçu, activité, notifications ; account:write marque uniquement les notifications comme lues.
apikey:read	Liste des clés du compte et journal d'utilisation (impossible de créer, modifier ou révoquer).
apikey:self	Implicite sur chaque clé : inspection de la clé appelante (GET /v1/apikeys/self).
ticket:read, ticket:write	Tickets de support.
aff:read, transfer:read	Programme d'affiliation et transferts de services — lecture seule.
k8s:read, k8s:write, k8s:create, k8s:scale, k8s:destroy, k8s:kubeconfig	Kubernetes (la création et la mise à l'échelle sont payantes ; le fichier kubeconfig donne les droits cluster-admin).
vpc:read, vpc:write, vpc:create, vpc:destroy	Private Cloud.
image:read, image:write	Images OS et ISO (le stockage est facturé à l'heure).
s3:read, s3:write, s3:create, s3:destroy, s3:keys	Object Storage (le secret S3 n'est affiché qu'une seule fois).
vpn:read, vpn:detail, vpn:write, vpn:create, vpn:destroy	VPN et proxy IPv6 (les détails de connexion incluent les mots de passe du proxy).
dedicated:read, dedicated:write, dedicated:console, dedicated:create, dedicated:destroy	Serveurs dédiés (création de commandes depuis le portefeuille ; la suppression réinstalle l'OS).
shield:read, shield:write, shield:agent	DDoS Shield, uniquement lorsque ce module est activé.

Un appel en dehors des portées de la clé renvoie 403 scope_required ; un chemin qu'aucune clé ne peut appeler renvoie 403 endpoint_not_public.

Ce qu'une clé ne peut jamais faire

Aucun scope n'ouvre l'accès à : recharger ou retirer de l'argent, modifier les 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. Celles-ci nécessitent toujours un navigateur connecté. Même une clé compromise ne peut toucher à l'argent ou au compte du client.

Règles sur lesquelles vous pouvez compter

Règle	Détail
Liée au site	Une clé fonctionne uniquement sur le site (domaine) où elle a été créée.
Limites de taux	Par clé et par compte : 120 et 300 requêtes par minute par défaut.
Idempotence	Les opérations qui coûtent de l'argent ou ne peuvent pas être répétées nécessitent un en-tête Idempotency-Key.
Quotas	Une clé est soumise aux mêmes quotas que le client.
Compte verrouillé	Les clés d'un client bloqué cessent de fonctionner (403 account_blocked).
Audit	La révocation par un administrateur est consignée dans le journal d'audit administrateur.

Vue administrateur

1. Ouvrez Customers › API keys (/customers/apikeys). Le tableau affiche le nom de la clé et les premiers caractères, le propriétaire, les périmètres, le statut, la dernière utilisation (heure, nombre de requêtes, IP) et l'expiration.
2. Filtrez par site si vous avez des revendeurs. Recherchez par nom, ID ou début de clé.
3. Cliquez sur Revoke pour arrêter une clé active, ou sur Log pour consulter son utilisation.
4. Les administrateurs voient et révoquent les clés mais ne peuvent ni les lire ni les créer pour les clients.

Vérification

1. Créez une clé avec le périmètre vm:read uniquement.
2. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" renvoie la liste des VM.
3. curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX" répond par 403 scope_required.
4. Révoquez la clé ; le premier appel répond désormais par 401 key_revoked.

Limites et notes

• La clé n'est plus jamais affichée. Traitez-la comme un mot de passe et stockez-la dans un gestionnaire de secrets ou un secret CI.
• Privilégiez une clé par script, des périmètres minimaux, une expiration courte et une liste d'adresses IP autorisées ; effectuez une rotation en créant une nouvelle clé et en révoquant l'ancienne.
• Les clés issues d'une connexion d'appareil (CLI, MCP) expirent par défaut au bout de 90 jours.
• Les ressources supprimées ou transférées ne sont pas affectées par la révocation d'une clé.

Dépannage

Symptôme	Cause	Solution
Erreur too_many_keys (422)	La limite de clés actives (10 par défaut) est atteinte	Révoquez une ancienne clé.
Erreur invalid_argument : aucun périmètre choisi	Aucun périmètre cochée	Cochez au moins un périmètre.
Erreur invalid_argument sur les IP autorisées	Une entrée n'est pas une IP ou une plage, la longueur du préfixe est incorrecte ou il y a plus de 20 entrées	Une IP ou un CIDR par ligne, par exemple 203.0.113.0/24.
La création est refusée pendant l'usurpation d'identité	impersonate_forbidden	Demandez au client de créer la clé.
401 key_expired	Date d'expiration dépassée	Créez une nouvelle clé.
401 key_ip_denied	IP de l'appelant absente de la liste autorisée	Ajoutez l'adresse IP ou effacez la liste.
401 api_keys_disabled	Fonctionnalité désactivée	Demandez à votre administrateur (paramètre api_keys_enabled).