Comptes de service
Un compte de service est une identité non humaine, rattachée à un espace de travail, qu'une charge de travail (par exemple un worker de workflow) utilise pour s'authentifier auprès de la plateforme Mistral. C'est un principal à part entière : il possède un nom, des rôles et ses propres identifiants, et n'est rattaché à aucune personne.
Exécuter une charge de travail sous un compte de service plutôt qu'avec la clé API d'un membre de l'équipe présente deux avantages :
- la charge de travail continue de fonctionner lorsque la clé de cette personne est renouvelée, ou lorsqu'elle quitte l'entreprise ;
- les journaux d'audit et les déploiements sécurisés désignent la charge de travail, et non une personne.
Utilisez un compte de service pour l'authentification de machine à machine, par exemple un worker de workflow s'exécutant dans votre cluster. Utilisez une clé API personnelle pour l'usage interactif, les scripts et le développement.
Comment une charge de travail s'authentifie
Un compte de service ne peut pas s'authentifier seul. Il lui faut au moins un identifiant, et il en existe deux types.
| Identifiant | Fonctionnement | Quand l'utiliser |
|---|---|---|
| Fédération d'identité de charge de travail | La charge de travail présente un jeton de courte durée signé par un émetteur de confiance. La plateforme le vérifie à l'aide de la clé publique de l'émetteur. Aucun secret stocké. | Une charge de travail s'exécutant dans un cluster Kubernetes ou derrière un autre émetteur OIDC. |
| Clé API | Une clé à longue durée de vie détenue par le compte de service. | Un worker s'exécutant en dehors de Kubernetes. |
Les deux se gèrent au même endroit : ouvrez le compte de service et cliquez sur Add new authentication. La fédération d'identité de charge de travail a sa propre configuration, décrite dans Fédération d'identité de charge de travail. L'ajout d'une clé API est décrit dans Ajouter une clé API.
Créer un compte de service
Un administrateur d'espace de travail crée le compte de service.
- Ouvrez Admin Console›Workspace›Service accounts ↗.
- Cliquez sur Create service account.
- Saisissez un Name (unique dans l'espace de travail) et une Description facultative.
- Cliquez sur Create.
| Champ | Obligatoire | Notes |
|---|---|---|
| Name | Oui | Un slug, unique dans l'espace de travail : une lettre minuscule suivie de lettres minuscules, de chiffres ou de traits d'union, 2 à 63 caractères (par exemple prod-worker). Une saisie en casse mixte est convertie en minuscules. Il ne peut pas être modifié après la création. |
| Description | Non | Texte libre pour indiquer l'usage du compte de service. Jusqu'à 4096 caractères. |
Rôles
Un nouveau compte de service ne dispose d'aucun rôle par défaut. Un administrateur de l'espace de travail lui accorde un ou plusieurs rôles après sa création ; tant qu'il n'en possède aucun, il ne peut rien faire sur la plateforme.
Les rôles attribuables à ce jour incluent, par exemple :
workflow_executor— accès programmatique à l'API, sans AI Studio ni gestion des identifiants. Permet à un worker d'enregistrer et d'exécuter des workflows.- Developer (
dev) — tout ce que permetworkflow_executor, plus l'accès à AI Studio et la gestion des identifiants.
Dans l'Admin Console
Ouvrez le compte de service, allez dans sa section Roles et sélectionnez un ou plusieurs rôles. Les modifications s'appliquent immédiatement.
Avec l'API
PUT /v1/service-accounts/<SERVICE_ACCOUNT_ID>/roles remplace les rôles du compte par ceux que vous passez dans role_ids. Il s'agit d'un remplacement complet : tout rôle détenu par le compte mais absent de la liste est révoqué, et un tableau vide supprime tous les rôles. Chaque entrée est un UUID de rôle ; récupérez les rôles attribuables et leurs UUID via GET /v1/service-accounts/assignable-roles.
curl -X PUT https://api.mistral.ai/v1/service-accounts/<SERVICE_ACCOUNT_ID>/roles \
-H "Content-Type: application/json" -H "x-api-key: $ADMIN_API_KEY" \
-d '{"role_ids": ["<ROLE_UUID>"]}'Consultez Rôles et permissions.
Ajouter une clé API
Une clé API détenue par un compte de service s'authentifie en tant que ce compte de service et hérite de ses rôles.
- Ouvrez le compte de service et cliquez sur Add new authentication.
- Dans la boîte de dialogue Add credential, choisissez API key.
- Saisissez éventuellement un Name pour identifier la clé par la suite.
- Définissez éventuellement une Expiration. Laissez le champ vide pour une clé sans expiration.
- Cliquez sur Create API key.
La clé n'est affichée qu'une seule fois, à sa création. Copiez-la et conservez-la dans votre gestionnaire de secrets : vous ne pourrez pas la récupérer ensuite.
| Champ | Obligatoire | Notes |
|---|---|---|
| Name | Non | Un libellé pour identifier la clé par la suite. |
| Expiration | Non | Le dernier jour de validité de la clé. Votre organisation peut imposer une durée de vie maximale. |
La clé est limitée à l'espace de travail du compte de service et aux connecteurs partagés uniquement. Vous ne pouvez pas la déplacer vers un autre espace de travail.
Une clé API est un secret permanent : toute personne qui la détient peut agir en tant que compte de service jusqu'à ce que la clé soit supprimée ou expire. Privilégiez la fédération d'identité de charge de travail lorsque votre charge de travail peut présenter un jeton signé par un émetteur.
Gérer les identifiants
Les deux types d'identifiants sont répertoriés à des endroits différents.
- Les identifiants d'identité de charge de travail figurent dans la liste Credentials du compte de service, avec leur sujet, leur émetteur de confiance et leur expiration. Consultez Gérer et renouveler.
- Les clés API figurent dans la section Clés API de l'espace de travail, aux côtés des clés détenues par des personnes. La colonne Principal indique le compte de service propriétaire ainsi qu'un badge Service account.
Supprimer un compte de service retire l'identité et ses identifiants : toute charge de travail qui les utilise cesse alors de s'authentifier.
Comptes de service et déploiements sécurisés
Un déploiement sécurisé restreint les principaux autorisés à enregistrer des workflows. Vous pouvez y associer un compte de service ; renouveler les identifiants d'identité de charge de travail de ce compte ne nécessite alors aucune modification du déploiement.
Une clé API s'associe séparément, en tant que clé API. Si votre worker s'authentifie avec la clé API d'un compte de service, ajoutez également cette clé au déploiement sécurisé.