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.

You can create and manage groups from Admin Panel›Administration›Groups ↗. On Enterprise plans, you can also use the Admin API.

• 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.

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 for how Workspace roles work, and Roles and permissions for role names and API fields.

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.

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.

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 and User provisioning.