---
title: User provisioning
sidebar_position: 6
description: Bulk-create or invite users, organize them into a user group, and grant them access to a Workspace with the Admin API.
---

# User provisioning with the Admin API

This guide walks through provisioning users with the Admin API: create users in bulk, organize them into a user group, and grant the group access to a Workspace. It then covers updating users and removing them from a Workspace.

:::info[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](https://mistral.ai/contact).
:::

<SectionTab as="h1" sectionId="before-you-start">Before you start</SectionTab>

You need an Admin API key created in the Admin Panel. Every request uses the base URL `https://api.mistral.ai/v1/admin` and the `x-api-key` header. See [Admin API authentication](/admin/admin-api/authentication).

<SectionTab as="h1" sectionId="create-users">Create users in bulk</SectionTab>

Send an array of users to create them in a single request. Each entry takes a role, an email, and a name.

```bash
curl -X POST https://api.mistral.ai/v1/admin/users \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '[
    {"role": "A", "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace"},
    {"role": "M", "email": "alan@example.com", "first_name": "Alan", "last_name": "Turing"}
  ]'
```

The response maps each email to the created user ID. Created users sign in by entering their email and completing the account recovery flow.

:::note
Role values such as `A` (Admin) and `M` (Member) are accepted. The singular `role` field is deprecated. Prefer `roles` / `role_names`. List the available roles and their UUIDs with `GET /v1/admin/roles`. See [Roles and permissions](/admin/identity-access/roles-permissions).
:::

<SectionTab as="h1" sectionId="invite-users">Invite users by email</SectionTab>

Instead of creating users directly, you can email invitations. Recipients accept the invite to join the Organization. Pass a comma-separated list to invite several people at once.

```bash
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": "M"}'
```

List or delete pending invitations:

```bash
# 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"
```

<SectionTab as="h1" sectionId="group-users">Group users</SectionTab>

A user group lets you manage and assign users together. Create the group:

```bash
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`. Add members by their user IDs:

```bash
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>"]}'
```

See [User groups](/admin/identity-access/groups) for the concept.

<SectionTab as="h1" sectionId="assign-workspace">Assign a group to a workspace</SectionTab>

Create a workspace, optionally making one user its admin:

```bash
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",
    "icon": "",
    "add_all_org_members": false,
    "admin_user_id": "<USER_UUID>"
  }'
```

The response includes the Workspace `uuid`. Provision every member of the group into the Workspace with a given role:

```bash
curl -X POST https://api.mistral.ai/v1/admin/user-groups/provision-workspace \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ADMIN_API_KEY" \
  -d '{
    "user_group_uuid": "<GROUP_UUID>",
    "workspace_uuid": "<WORKSPACE_UUID>",
    "workspace_role": "M"
  }'
```

<SectionTab as="h1" sectionId="lifecycle">Manage the user lifecycle</SectionTab>

Update a user's role or subscriptions:

```bash
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": "M", "subscription_types": ["CHAT", "MISTRAL_CODE"]}'
```

Remove users from a Workspace. This deletes all of their permissions in that workspace:

```bash
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>"}]}'
```

<SectionTab as="h1" sectionId="next-steps">Next steps</SectionTab>

<UsefullLinkContainer>
  <LinkCard href="/admin/admin-api/usage-metrics" title="Usage metrics" />
  <LinkCard href="/admin/identity-access/groups" title="User groups" />
</UsefullLinkContainer>