Intégration API

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émentLimite
Durée de validité1 à 90 jours
Projetun seul projet, donc tous ses dépôts
Clés valides par compte20 (une place libre est nécessaire pour renouveler)
Droitschoisis un par un, jamais plus que votre rôle actuel

Créer une clé#

  1. Ouvrez votre compte, puis Gérer mes clés API. L'écran Mes clés API s'affiche (/account/api-keys).
  2. 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.
  3. Dans la carte Créer une clé, renseignez le Libellé, par exemple « Intégration CI ».
  4. Indiquez la Durée en jours.
  5. 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é.
  6. Sous Droits de la clé, cochez les droits utiles, et seulement eux.
  7. 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 APIRôle minimal du propriétaire
Lire les projetsprojects:readLecteur
Lire les dépôtsrepositories:readLecteur
Lire les exécutionsruns:readLecteur
Démarrer une exécutionruns:createOpérateur
Annuler une exécutionruns:cancelOpérateur
Lire les auditsaudits:readLecteur
Demander un auditaudits:createOpérateur
Lire les rapportsreports:readLecteur
Lire la consommationusage:readLecteur

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é#

  1. Dans l'inventaire, cliquez sur Renouveler sous la clé.
  2. Saisissez la Durée de la nouvelle clé en jours.
  3. 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#

SituationQue faire
Le bouton Créer la clé est inactifAucun projet n'est disponible pour votre compte, ou un secret est encore affiché : masquez-le.
Un message d'erreur s'affiche à la créationVé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.