Clés API personnelles
Une clé API personnelle permet à un outil d'appeler l'API en votre nom. Elle est rattachée à votre compte pour toujours : personne ne peut la créer pour vous ni la transférer.
Qui peut le faire : tout compte actif crée, renouvelle et révoque ses propres clés. L'Administrateur consulte l'inventaire de l'organisation et peut révoquer la clé d'un autre compte, sans jamais voir son secret.
Limites d'une clé#
| Élément | Limite |
|---|---|
| Durée de validité | 1 à 90 jours |
| Projet | un seul projet, donc tous ses dépôts |
| Clés valides par compte | 20 (une place libre est nécessaire pour renouveler) |
| Droits | choisis un par un, jamais plus que votre rôle actuel |
Créer une clé#
- Ouvrez votre compte, puis Gérer mes clés API. L'écran Mes clés API s'affiche (
/account/api-keys). - La création exige une vérification récente de moins de 5 minutes. Si elle manque, cliquez sur Vérifier mon identité et saisissez le code de sécurité reçu par e-mail. Voir Session et vérification récente.
- Dans la carte Créer une clé, renseignez le Libellé, par exemple « Intégration CI ».
- Indiquez la Durée en jours.
- Sous Projet de la clé, choisissez le projet que la clé pourra atteindre. Charger plus de projets affiche la suite de la liste. Pour un autre projet, créez une autre clé.
- Sous Droits de la clé, cochez les droits utiles, et seulement eux.
- Cliquez sur Créer la clé.
L'encadré Copiez cette clé maintenant affiche le Secret de la clé. Copiez-le dans votre gestionnaire de secrets, puis cliquez sur Masquer le secret. Le secret est aussi effacé quand vous quittez la page.
La clé a la forme 101m_<identifiant>.<secret>. L'identifiant est public ; le secret ne doit jamais apparaître dans un dépôt, un journal ou une URL.
Choisir les droits#
Les droits proposés dépendent de votre rôle sur les projets. Cochez le minimum nécessaire à l'outil.
| Droit affiché | Scope API | Rôle minimal du propriétaire |
|---|---|---|
| Lire les projets | projects:read | Lecteur |
| Lire les dépôts | repositories:read | Lecteur |
| Lire les exécutions | runs:read | Lecteur |
| Démarrer une exécution | runs:create | Opérateur |
| Annuler une exécution | runs:cancel | Opérateur |
| Lire les audits | audits:read | Lecteur |
| Demander un audit | audits:create | Opérateur |
| Lire les rapports | reports:read | Lecteur |
| Lire la consommation | usage:read | Lecteur |
Exemples de profils :
- Tableau de bord : Lire les projets, Lire les exécutions, Lire la consommation.
- CI qui déclenche des audits : Lire les audits, Demander un audit, Lire les rapports.
- Outil de maintenance : Lire les exécutions, Démarrer une exécution, Annuler une exécution. Ajoutez Lire les exécutions pour que les conflits indiquent l'exécution existante.
Consulter l'inventaire#
La carte Inventaire liste vos clés avec leur libellé, leurs droits et leur état. Le filtre État propose Actives, Expirées, Révoquées et En fin de rotation. Le lien Activité des clés de ce propriétaire ouvre le journal des actions filtré sur les appels par clé. Voir Journal des actions.
L'Administrateur dispose de Inventaire des clés de l'organisation (/admin/api-keys), avec un filtre Propriétaire. Voir Inventaire des clés API.
Renouveler une clé#
- Dans l'inventaire, cliquez sur Renouveler sous la clé.
- Saisissez la Durée de la nouvelle clé en jours.
- Cliquez sur Confirmer le renouvellement, puis copiez le nouveau secret.
La nouvelle clé garde le même propriétaire, le même projet et les mêmes droits, si votre compte les détient toujours. L'ancienne clé reste valable au plus cinq minutes : remplacez-la sans attendre dans vos outils. Une clé déjà renouvelée ne peut pas l'être une seconde fois. Le renouvellement exige aussi une vérification récente.
Révoquer une clé#
Cliquez sur Révoquer, puis sur Confirmer la révocation. Les appels suivants avec cette clé reçoivent 401. Une demande d'exécution encore en attente, faite avec cette clé, est annulée.
Erreurs courantes#
| Situation | Que faire |
|---|---|
| Le bouton Créer la clé est inactif | Aucun projet n'est disponible pour votre compte, ou un secret est encore affiché : masquez-le. |
| Un message d'erreur s'affiche à la création | Vérification récente expirée, plafond de 20 clés atteint ou droit non autorisé pour votre rôle. Vérifiez votre identité, puis réessayez. |
| « Action indisponible. Vérifiez l'inventaire avant de réessayer. » | La réponse s'est perdue. Consultez l'inventaire : si une clé a été créée sans que vous ayez son secret, révoquez-la. |
Pour continuer#
Utilisez la clé dans vos appels : Authentification et scopes.