Clés d'API

L'écran Clés d'API permet de créer des clés du tenant à portée limitée pour une application ou un pipeline, de les faire tourner et de les révoquer ; le secret est affiché une seule fois, à la création ou à la rotation. Chemin dans le portail : /admin/api-keys. Il sert aux administrateurs du tenant (tenant_admin), aux développeurs (developer, pour leurs propres clés) et aux responsables sécurité (security_officer, pour la réponse aux incidents).

Ce que montre l'écran

Un tableau Clés d'API avec Actualiser et Nouvelle clé d'API :

Colonne	Contenu
Nom	Nom de la clé.
Préfixe	Premiers caractères de la clé, pour la reconnaître dans les journaux.
Portées	Portées accordées, par exemple models:invoke, agents:run.
Rôles	Rôles portés par la clé.
Révoquée	Oui une fois la clé révoquée.
Dernière utilisation	Date de la dernière utilisation.
Expire	Date d'expiration, vide pour une clé sans expiration.
Créé	Date de création.

La liste est paginée. Un développeur ne voit que les clés qu'il a créées ; tenant_admin, security_officer et platform_admin voient toutes les clés du tenant. État vide : Aucune clé d'API, « Créez une clé à portée limitée pour une application ou un pipeline. »

Après une création ou une rotation, la boîte Secret créé affiche la clé avec un bouton de copie et l'avertissement « Copiez-le maintenant : il n'est affiché qu'une fois et ne pourra plus être récupéré. »

Actions

Bouton ou action	Ce qu'il fait	Appel d'API	Rôles
Ouverture de l'écran, Actualiser	Lit les clés page par page.	GET /v1/api-keys	tenant_admin, security_officer, developer
Nouvelle clé d'API puis Créer	Formulaire Nom (obligatoire), Portées (liste obligatoire ; suggestions models:invoke, agents:run, tools:invoke, rag:query, finops:read, admin:*), Expire (date et heure, par exemple 2027-01-01T00:00:00Z). Le secret est affiché une fois.	POST /v1/api-keys	tenant_admin, developer
Rotation	Confirmation du navigateur « Rotation <nom> ? Cette action est enregistrée dans le journal d'audit. », puis une clé de remplacement avec les mêmes nom, portées et rôles ; le nouveau secret est affiché une fois. Le portail n'envoie pas de période de grâce.	POST /v1/api-keys/{id}/rotate	tenant_admin, security_officer, developer (ses clés)
Révoquer	Confirmation destructive, puis la clé cesse de fonctionner.	DELETE /v1/api-keys/{id} (impact : GET /v1/lineage/graph)	tenant_admin, security_officer, developer (ses clés)

Rôles

D'après services/control-plane/src/eai/domains/identity/__init__.py :

• Lister, faire tourner et révoquer exigent tenant_admin, security_officer ou developer ; créer exige tenant_admin ou developer (platform_admin passe toujours).
• Un développeur ne gère que les clés qu'il a créées : une autre clé répond not_found.
• Une clé ne reçoit jamais une portée que l'appelant ne détient pas (scope_not_held), ni un rôle au-dessus du sien ; le rôle platform_admin est réservé à un platform_admin.
• Un security_officer sans rôle d'administrateur fait tourner toute clé sauf une clé qui porte tenant_admin.

danger

Le secret n'est affiché qu'une fois. Rangez-le tout de suite dans le gestionnaire de secrets de l'application ; s'il est perdu, faites tourner la clé. Révoquez immédiatement une clé qui a fuité.

Tâches courantes

Créer une clé pour un pipeline

1. Ouvrir le formulaire. Bouton Nouvelle clé d'API. Résultat attendu : le formulaire latéral. En cas d'échec : forbidden à l'envoi si vous n'êtes ni tenant_admin ni developer.
2. Donner les portées les plus étroites. Nom : ci-pipeline ; Portées : seulement ce que le pipeline appelle, par exemple agents:run ; Expire : une date. Puis Créer. Résultat attendu : la boîte Secret créé. En cas d'échec : forbidden avec scope_not_held si vous demandez une portée que vous ne détenez pas.
3. Copier le secret. Bouton de copie de la boîte, puis collez-le dans le coffre de secrets du pipeline. Résultat attendu : le pipeline s'authentifie. En cas d'échec : la boîte a été fermée avant la copie ; faites tourner la clé pour obtenir un nouveau secret.

Faire tourner une clé

1. Ouvrir l'action. Menu de la ligne > Rotation, acceptez la confirmation du navigateur. Résultat attendu : la boîte Secret créé avec le nouveau secret. En cas d'échec : not_found pour une clé d'un autre développeur.
2. Remplacer le secret là où il sert. Résultat attendu : le client fonctionne avec la nouvelle clé ; la Dernière utilisation de la nouvelle ligne avance. En cas d'échec : le client envoie encore l'ancienne clé ; mettez à jour sa configuration.

Révoquer une clé qui a fuité

1. Révoquer. Menu de la ligne > Révoquer, confirmez. Résultat attendu : Révoquée indique oui. En cas d'échec : forbidden si votre rôle ne gère pas les clés.

Dépannage

Symptôme	Cause	Correction
forbidden (HTTP 403) avec scope_not_held	Une portée demandée n'est pas détenue par votre propre identité.	Ne demandez que des portées que vous détenez, ou adressez-vous à un tenant_admin.
forbidden (HTTP 403) avec required_roles	Votre rôle ne peut pas lister, créer ou faire tourner les clés, ou la clé porte un rôle au-dessus du vôtre.	Adressez-vous à un tenant_admin.
not_found (HTTP 404) sur Rotation ou Révoquer	La clé appartient à un autre développeur, ou elle n'existe plus.	Adressez-vous à son propriétaire ou à un tenant_admin.
tenant_required (HTTP 403)	La session n'agit pas dans un tenant.	Connectez-vous avec un compte du tenant.
Le secret est perdu	La boîte Secret créé a été fermée.	Faites une Rotation de la clé.
Erreur de validation sur Expire	La valeur n'est pas une date et une heure.	Utilisez le format 2027-01-01T00:00:00Z.

Pages liées

• Identités de service
• Membres et rôles
• Référence de l'API
• Documentation sécurité