---
title: Groups
sidebar_position: 3
description: Group users to manage Workspace access and roles at scale.
---

# User groups

A user group is a named collection of users that you manage and assign together. Instead of granting Workspace access one user at a time, you assign a group to a Workspace once, and every member gains access with the roles you choose.

Available on **Enterprise** plans.

You can create and manage groups from <AppLink href="https://admin.mistral.ai/organization/groups" path={["Admin Panel", "Administration", "Groups"]} />. On Enterprise plans, you can also use the [Admin API](/admin/admin-api/manage-groups-roles).

<SectionTab as="h1" sectionId="how-it-works">How user groups work</SectionTab>

- A group bundles users under a single name and description.
- You add or remove members by their user ID.
- You assign a group to a Workspace with one or more roles. Members get access to that Workspace with those roles while they're in the group.
- A group can be assigned to more than one Workspace, and a user can belong to more than one group. If several of a user's groups are assigned to the same Workspace, the user gets all of their roles in it.

<SectionTab as="h1" sectionId="groups-Workspaces-roles">Groups, Workspaces, and roles</SectionTab>

User groups sit alongside the existing access model:

- **Organization**: the top-level account that users belong to.
- **Workspace**: an isolated environment with its own members, API keys, and usage. Each member has one or more Workspace roles.
- **User group**: a convenience layer for assigning many users to a Workspace at once, with chosen roles.

When you assign a group to a Workspace, you set the Workspace roles its members get. See [Your first Workspace](/admin/workspaces/your-first-workspace) for how Workspace roles work, and [Roles and permissions](/admin/identity-access/roles-permissions) for role names and API fields.

<SectionTab as="h2" variant="secondary" sectionId="access-and-roles">Access and roles</SectionTab>

A user has **access** to a Workspace when they hold at least one role in it. Their **roles** determine what they can do there.

A user can get roles in a Workspace in two ways:

- **Directly**, when they're added to the Workspace as an individual.
- **Through a group**, when a group they belong to is assigned to the Workspace.

Their roles are the combination of all these sources. They keep access as long as at least one source gives them a role.

Removing a user from a group removes only the roles that group gave them. If they still have roles directly or through another group, they keep access to the Workspace.

<SectionTab as="h1" sectionId="externally-managed-groups">Externally managed groups</SectionTab>

If your Organization uses an identity provider with SSO or SCIM provisioning, some groups and members can be externally managed. Your identity provider is the source of truth for their identity, membership, or lifecycle.

Externally managed users and groups cannot be edited directly in Mistral for fields owned by the identity provider. Manage those fields in your identity provider, then let the next sync update Mistral.

<SectionTab as="h1" sectionId="typical-workflow">Typical workflow</SectionTab>

1. Create a group.
2. Add members to the group.
3. Assign the group to a Workspace with a role.

On Enterprise plans, you can make the same changes with the Admin API. For the corresponding API calls, see [Manage groups and roles](/admin/admin-api/manage-groups-roles) and [User provisioning](/admin/admin-api/user-provisioning).

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

<UsefullLinkContainer>
  <LinkCard href="/admin/admin-api/user-provisioning" title="User provisioning" />
  <LinkCard href="/admin/admin-api/overview" title="Admin API" />
</UsefullLinkContainer>