Créer et gérer vos jetons d'API

L'API de l'espace client permet à vos propres outils de lire vos services, leur état et vos factures, et même d'agir sur vos machines : un tableau de bord interne, un script de déploiement, votre outil de supervision. Chaque outil se présente avec un jeton que vous créez dans Mon profil › API. Cette page est réservée aux contacts d'accès complet.

Créer un jeton

1. Cliquez sur Nouveau jeton.
2. Donnez-lui un Nom qui dit à quoi il sert, par exemple « Pipeline GitLab production ».
3. Choisissez quand il Expire : 30 jours, 90 jours, 1 an (par défaut) ou Jamais.
4. Cochez ses Portées, ou partez d'un modèle avec Partir de : Tableau de bord (lecture seule), Comptabilité (factures), Chaîne CI (déploiements), Exploitation (machines).
5. Cliquez sur Créer, puis copiez le jeton affiché (il commence par mmcp_).

Le jeton n'est montré qu'une seule fois. Rangez-le comme un mot de passe, dans un gestionnaire de secrets ou les secrets de votre CI : quiconque le détient agit avec ses portées.

Les portées

Les portées sont regroupées en trois familles :

• Lire vos données : lecture (services, état, incidents, maintenances, sondes) et facturation (factures) ;
• Configurer et annoter : sondes HTTP, silences d'alertes, annotations de déploiement, prise en charge des problèmes en cours, enregistrements DNS, clés SSH et scripts de démarrage de votre compte ;
• Agir sur vos machines : actions Monit, actions sur les VM, sauvegardes à la demande, snapshots, règles de pare-feu des VM, réseaux privés entre vos serveurs, réinstallation et mode rescue de vos VPS, restauration d'une VM depuis ses sauvegardes, commande d'un nouveau VPS à partir d'une sauvegarde.

Les portées marquées « agit sur vos machines » ou « destructif » méritent une expiration courte et des outils de confiance. Vous ne pouvez cocher que ce que vos propres droits permettent : une portée grisée correspond à un droit que vous n'avez pas (les actions sur les VM, par exemple).

Un jeton par rôles : sur certains services seulement

Quand votre société utilise les rôles, le formulaire propose deux façons de définir un jeton : Par portées (ci-dessus) ou Par rôles. Un jeton par portées agit sur tout ce à quoi vous avez accès ; un jeton par rôles ne fait que ce que permettent les rôles choisis, sur les services et les domaines choisis.

1. Dans le formulaire, cliquez sur Par rôles.
2. Cochez un ou plusieurs Rôles. Seuls les rôles que vous tenez vous-même sont proposés.
3. Choisissez Tous les services et domaines ou Certains seulement, puis cochez les services et les domaines concernés.
4. Cliquez sur Créer.

Exemple : pour votre chaîne de déploiement, un jeton « deploy-web » avec le rôle « VM : accès complet » sur web-9101 seulement. Il peut créer un snapshot ou redémarrer cette machine ; il ne voit ni vos autres machines ni vos factures.

À savoir :

• Un jeton par rôles n'a pas de portée : dans la liste, il affiche ses rôles et ce sur quoi ils portent.
• Il ne dépasse jamais vos propres droits : si vous perdez un rôle, le jeton perd aussitôt ce que ce rôle lui donnait. Un compte de service par rôles, lui, garde les rôles reçus à sa création.
• Un rôle que vous ne tenez que sur certains services ne peut être donné que sur ceux-là.

Gérer les jetons

La liste montre pour chaque jeton son nom, le début du jeton, ses portées, son auteur, sa dernière utilisation (ou « jamais utilisé ») et sa date d'expiration. Révoquer le désactive immédiatement : les programmes qui l'utilisent s'arrêtent aussitôt.

Compte de service : un jeton qui appartient à la société

Un jeton ordinaire est lié à la personne qui l'a créé : si son accès est désactivé ou retiré, le jeton s'arrête. C'est gênant pour un robot (votre chaîne de déploiement, votre supervision) qui doit continuer de tourner quand un collègue quitte l'entreprise.

Si notre équipe a ouvert la fonction pour votre compte, cochez Compte de service en créant le jeton :

• le jeton appartient à votre société, pas à vous ;
• il garde les droits que vous avez le jour de sa création, même si votre accès change ensuite ;
• il continue de fonctionner si vous êtes désactivé ou retiré de l'équipe ;
• ses actions apparaissent dans le journal d'activité sous « service-account », avec le nom du jeton.

Dans la liste, il porte la pastille Compte de service. Il se révoque comme un autre jeton, par n'importe quel contact d'accès complet.

Exemple : vous créez le jeton « ci-deploy » en compte de service pour votre pipeline. Six mois plus tard vous changez de poste et votre accès est retiré : le pipeline continue de fonctionner.

Réservez-le aux robots : pour une personne, un jeton ordinaire est plus sûr, car il s'arrête avec son accès.

Bon à savoir

• Un jeton agit avec les droits de la personne qui l'a créé, vérifiés à chaque appel. Si ce contact est désactivé, retiré ou perd un droit, le jeton perd l'accès correspondant.
• Les adresses autorisées de votre société s'appliquent aussi aux appels d'API.
• Une société peut avoir au plus 20 jetons actifs. Révoquez ceux qui ne servent plus.
• Une nouvelle portée ajoutée plus tard n'est jamais donnée aux jetons existants : créez un nouveau jeton si vous en avez besoin.