Manage groups and roles with the Admin API

Create and manage user groups, assign them to Workspaces, and look up roles. For the concept, see Groups.

Information

Enterprise plans only

The Admin API is available only on Enterprise plans, and access isn't self-serve. On other plans, you can't create an Admin API key, and a standard API key doesn't work with admin endpoints. To request access, contact your Mistral account team or our sales team.

Before you start

All requests use the base URL https://api.mistral.ai/v1/admin and an Admin API key in the x-api-key header. See Authentication and Admin API keys.

Manage groups

List groups (page, page_size, search), or create one. name is required; description is optional.

# List groups
curl https://api.mistral.ai/v1/admin/user-groups \
  -H "x-api-key: $ADMIN_API_KEY"

# Create a group
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"}'

# List groups
curl https://api.mistral.ai/v1/admin/user-groups \
  -H "x-api-key: $ADMIN_API_KEY"

# Create a group
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"}'

The response includes the group uuid. Get, update, or delete a group by its UUID:

curl https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

curl -X PATCH https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID> \
  -H "Content-Type: application/json" -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"description": "Updated description"}'

curl -X DELETE https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

curl https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

curl -X PATCH https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID> \
  -H "Content-Type: application/json" -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"description": "Updated description"}'

curl -X DELETE https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

Manage members

List members, or add and remove them with a user_uuids array.

# List members
curl https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/members \
  -H "x-api-key: $ADMIN_API_KEY"

# Add members
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>"]}'

# Remove members
curl -X DELETE 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>"]}'

# List members
curl https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/members \
  -H "x-api-key: $ADMIN_API_KEY"

# Add members
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>"]}'

# Remove members
curl -X DELETE 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>"]}'

Assign a group to a workspace

Assigning a group to a Workspace gives its members access to that Workspace. Their roles determine what they can do there (see Roles).

When you assign a group to a Workspace:

Every member of the group gets the assigned roles in that Workspace.
New members get the roles when they join the group.
Members removed from the group lose the roles it gave them, and lose access unless they have roles from another source (see Access and roles).

# List a group's Workspace assignments
curl https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/workspaces \
  -H "x-api-key: $ADMIN_API_KEY"

# Assign the group to a Workspace
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": ["user"]}'

# Update the roles on an assignment
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": ["workspace_admin"]}'

# Remove the group from a workspace
curl -X DELETE https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/workspaces/<WORKSPACE_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

# List a group's Workspace assignments
curl https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/workspaces \
  -H "x-api-key: $ADMIN_API_KEY"

# Assign the group to a Workspace
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": ["user"]}'

# Update the roles on an assignment
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": ["workspace_admin"]}'

# Remove the group from a workspace
curl -X DELETE https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/workspaces/<WORKSPACE_UUID> \
  -H "x-api-key: $ADMIN_API_KEY"

Set a group's Organization role

curl -X PATCH https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/organization-role \
  -H "Content-Type: application/json" -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"organization_role": "member"}'

curl -X PATCH https://api.mistral.ai/v1/admin/user-groups/<GROUP_UUID>/organization-role \
  -H "Content-Type: application/json" -H "x-api-key: $ADMIN_API_KEY" \
  -d '{"organization_role": "member"}'

Roles

List every role and its UUID. RBAC must be enabled for the Organization.

curl https://api.mistral.ai/v1/admin/roles \
  -H "x-api-key: $ADMIN_API_KEY"

curl https://api.mistral.ai/v1/admin/roles \
  -H "x-api-key: $ADMIN_API_KEY"

The response groups roles into organization_roles and workspace_roles.

Organization roles

`role_name`	Access
`member`	Product usage; manages their own profile
`billing_manager`	Subscriptions, invoices, and payment methods; cannot change Organization settings
`organization_admin`	Full control of the Organization

Workspace roles

`role_name`	Access
`user`	le Chat and its features; no Studio
`dev`	Studio and all primitives (agents, fine-tuning, etc.); no le Chat
`mistral_code_user`	Mistral Code (requires a seat)
`billing`	Usage and cost reports only
`workspace_contributor`	All product features (`user`, `dev`, `mistral_code_user`); no management or observability
`workspace_admin`	Workspace contributor plus Workspace administration; no observability
`observability_viewer`	Observability product

Note

GET /v1/admin/roles is the authoritative list of roles and their UUIDs.