Créer et révoquer une clé d'API

Une clé d’API authentifie la CLI et l’API. Ce guide crée une clé, la range au bon endroit, puis la révoque.

Résultat attendu : une clé qui commence par hgdc_host_, avec ses portées et sa date d’expiration, visible dans la liste de ton organisation et révocable depuis la liste.

Avant de commencer : être admin ou propriétaire de l’organisation. Les membres ne voient pas l’onglet Clés d’API.

Créer une clé

1. Ouvre l'onglet Clés d'API

   Dans ton organisation, ouvre Clés d’API, puis clique Créer une clé.

2. Donne-lui un nom parlant

   Choisis un nom qui dit où la clé sert, par exemple Poste de Léa ou CI GitHub. Il t’aidera à savoir quelle clé révoquer.

3. Choisis ses portées et sa durée

   Coche le moins de portées possible (voir plus bas). Choisis combien de temps elle vaut : 30 jours, 90 jours (proposé), 1 an ou sans fin.

4. Copie la clé tout de suite

   La fenêtre Nouvelle clé d’API affiche la clé complète une seule fois. Clique Copier la clé et range-la dans un gestionnaire de mots de passe.

   Host ne garde qu’une empreinte de la clé. Si tu la perds, aucune copie n’est possible : crée une nouvelle clé et révoque l’ancienne.

   Vérification : la clé apparaît dans Clés actives avec son nom et la date de création.

Choisir les portées

Portée	Ce qu’elle permet
host:read	Lire les projets, les déploiements, les domaines
host:deploy	Déployer, mettre en production, revenir en arrière, annuler un build
host:env_read	Lire les variables d’environnement (vercel pull, vercel env ls)
host:env_write	Créer, modifier et supprimer des variables. Donne aussi la lecture
host:domains	Ajouter, vérifier et retirer des domaines
host:write	Tout, y compris créer un projet

Toute portée donne la lecture. Pour une CI qui déploie, host:deploy et host:env_read suffisent : c’est le choix proposé. Une portée qui manque répond 403 avec son nom dans le message.

Les deux sortes de clés

Sorte de clé	Qui la crée	Ce qu’elle peut faire
Clé d’organisation	Un admin ou un propriétaire, dans la console	Tous les projets de l’organisation, selon ses portées
Clé de projet	L’app GitHub, à l’import d’un dépôt	Un seul projet, avec host:deploy et host:env_read. Tout autre projet répond 404

Pour ton poste de développement, prends une clé d’organisation. Pour un dépôt, laisse l’app GitHub poser sa clé de projet.

Une clé d’organisation lit les variables non sensibles de tous les projets avec vercel pull. Ne la mets jamais dans un dépôt, ni dans du code envoyé au navigateur.

Utiliser la clé

La CLI lit la clé dans la variable VERCEL_TOKEN, qui évite de l’écrire dans l’historique du shell :

export VERCEL_TOKEN=hgdc_host_…
vercel --api https://api.host.hgdc.ch deploy

Pour une requête HTTP, envoie-la dans l’en-tête Authorization :

curl https://api.host.hgdc.ch/v2/user \
  -H "Authorization: Bearer $VERCEL_TOKEN"

Révoquer une clé

1. Repère la clé

   Dans Clés actives, regarde la date de Dernière utilisation. Une clé inutilisée depuis longtemps peut être révoquée sans risque.

2. Révoque-la

   Clique Révoquer la clé, puis confirme.

   Vérification : la clé disparaît de Clés actives. Une requête avec cette clé répond 403 avec le code forbidden.

Une clé cesse aussi de fonctionner à sa date d’expiration, et quand la personne qui l’a créée quitte l’organisation dans Account. Les anciennes clés ah_… restent acceptées, avec un accès complet : remplace-les par une clé à portées quand tu peux.

Si ça ne marche pas

• La CLI répond 403, avec le message « Clé d’API absente ou invalide » : la clé est mal copiée, ou elle a été révoquée. Voir Dépannage.
• Le message « Cette clé est limitée à un autre projet » apparaît : tu utilises la clé d’un dépôt pour un autre projet. Crée une clé d’organisation.

Voir aussi

• Clés d’API et sécurité : ce que Host garde et ce qu’il ne garde pas.
• Référence de l’API : l’en-tête, la portée et les limites.
• Brancher un agent IA : la même clé ouvre le serveur MCP.