Provisionnement des utilisateurs avec l’API Admin
Ce guide explique comment provisionner des utilisateurs avec l’API Admin :
- Créer ou inviter des utilisateurs avec un rôle Organisation.
- Créer un groupe d’utilisateurs et y ajouter les utilisateurs.
- Créer un espace de travail.
- Attribuer le groupe à l’espace de travail avec des rôles d’espace de travail.
Il couvre ensuite la mise à jour des utilisateurs et le retrait de leurs accès.
Réservé aux plans Entreprise
L’API Admin est disponible uniquement sur les plans Entreprise, et l’accès n’est pas en libre-service. Sur les autres plans, vous ne pouvez pas créer de clé API Admin, et une clé API standard ne fonctionne pas avec les endpoints d’administration. Pour demander l’accès, contactez votre équipe de compte Mistral ou notre équipe commerciale.
Avant de commencer
Vous avez besoin d’une clé API Admin créée dans le Panneau Admin. Chaque requête utilise l’URL de base https://api.mistral.ai/v1/admin et l’en-tête x-api-key. Consultez Authentification de l’API Admin.
Attribuez les rôles par leur nom avec role_names :
- Rôles Organisation :
member,billing_manager,organization_admin. - Rôles d’espace de travail : par exemple
user,workspace_contributor,workspace_admin.
Listez tous les rôles et leurs UUID avec GET /v1/admin/roles. Consultez Rôles et permissions pour savoir ce que chaque rôle permet.
Créer plusieurs utilisateurs
Envoyez un tableau d’utilisateurs pour les créer dans une seule requête. Chaque objet doit inclure email, first_name, last_name et des rôles Organisation dans role_names. Attribuez éventuellement des sièges produit avec subscription_types (CHAT, MISTRAL_CODE).
curl -X POST https://api.mistral.ai/v1/admin/users \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '[
{"email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace", "role_names": ["organization_admin"]},
{"email": "alan@example.com", "first_name": "Alan", "last_name": "Turing", "role_names": ["member"], "subscription_types": ["CHAT"]}
]'La réponse associe chaque adresse e-mail à l’identifiant de l’utilisateur créé dans email_to_user_id, et liste les adresses refusées dans invalid_emails. Les utilisateurs créés se connectent en saisissant leur adresse e-mail et en suivant la procédure de récupération du compte.
Les champs singuliers role et role_name, ainsi que les anciennes valeurs comme A et M, sont obsolètes. Utilisez role_names.
Inviter des utilisateurs par e-mail
Au lieu de créer les utilisateurs directement, vous pouvez envoyer des invitations par e-mail. Les destinataires acceptent l’invitation pour rejoindre l’Organisation. Séparez les adresses par des virgules pour inviter plusieurs personnes à la fois.
curl -X POST https://api.mistral.ai/v1/admin/users-invite \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{"email": "grace@example.com,katherine@example.com", "role_names": ["member"]}'Les utilisateurs invités n’obtiennent un identifiant utilisateur qu’après avoir accepté l’invitation. Ajoutez-les à un groupe à ce moment-là.
Listez ou supprimez les invitations en attente :
# List invitations
curl https://api.mistral.ai/v1/admin/users-invite \
-H "x-api-key: $ADMIN_API_KEY"
# Delete an invitation by its UUID
curl -X DELETE https://api.mistral.ai/v1/admin/users-invite/<INVITATION_UUID> \
-H "x-api-key: $ADMIN_API_KEY"Regrouper des utilisateurs
Un groupe d’utilisateurs vous permet de donner accès à plusieurs utilisateurs en une seule fois. Créez le groupe :
curl -X POST https://api.mistral.ai/v1/admin/user-groups \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{"name": "Interns", "description": "User group for interns"}'La réponse inclut l’uuid du groupe. Ajoutez des membres à l’aide de leurs identifiants utilisateur :
curl -X POST https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/members \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{"user_uuids": ["<USER_UUID_1>", "<USER_UUID_2>"]}'Pour en savoir plus, consultez Groupes pour le concept et Gérer les groupes et les rôles pour tous les endpoints de groupe.
Créer un espace de travail
Créez un espace de travail. admin_user_id est obligatoire : cet utilisateur devient administrateur de l’espace de travail.
curl -X POST https://api.mistral.ai/v1/admin/workspaces \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{
"name": "MySpace",
"description": "Small workspace",
"add_all_org_members": false,
"admin_user_id": "<USER_UUID>"
}'La réponse inclut l’uuid de l’espace de travail.
Attribuer le groupe à l’espace de travail
Attribuez le groupe à l’espace de travail avec un ou plusieurs rôles d’espace de travail. Chaque membre du groupe reçoit ces rôles, y compris les utilisateurs que vous ajoutez au groupe plus tard.
curl -X POST https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/workspaces \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{"workspace_uuid": "<WORKSPACE_UUID>", "role_names": ["workspace_contributor"]}'Modifiez les rôles d’une attribution existante :
curl -X PATCH https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/workspaces/<WORKSPACE_UUID> \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{"role_names": ["user"]}'POST /v1/admin/user-groups/provision-workspace est obsolète. Utilisez les endpoints ci-dessus.
Gérer le cycle de vie des utilisateurs
Mettez à jour les rôles Organisation ou les sièges produit d’un utilisateur. role_names est obligatoire :
curl -X PATCH https://api.mistral.ai/v1/admin/users/<USER_UUID> \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{"role_names": ["member"], "subscription_types": ["CHAT", "MISTRAL_CODE"]}'Retirez des utilisateurs d’un groupe ou le groupe entier d’un espace de travail avec les endpoints de groupe de Gérer les groupes et les rôles. Les membres retirés d’un groupe perdent les rôles d’espace de travail que celui-ci leur avait attribués.
Retirez les utilisateurs ajoutés directement à un espace de travail. Cette opération supprime leurs rôles directs dans cet espace de travail, mais pas les accès qu’ils obtiennent par un groupe :
curl -X DELETE https://api.mistral.ai/v1/admin/workspaces/<WORKSPACE_UUID>/remove-users \
-H "Content-Type: application/json" \
-H "x-api-key: $ADMIN_API_KEY" \
-d '{"members": [{"user_uuid": "<USER_UUID_1>"}, {"user_uuid": "<USER_UUID_2>"}]}'