> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Groups

> Put organization members into user groups, then give each user group a role and access policies in the workspaces it can access.

A user group is a set of organization members, such as a team, that you manage together. You can give a user group access to several workspaces, with a specific role in each. User group members who belong to those workspaces receive the user group's role there. User Groups build on [role-based access control (RBAC)](https://docs.langchain.com/langsmith/rbac.md) and [attribute-based access control (ABAC)](https://docs.langchain.com/langsmith/abac.md).

> [!NOTE]
>
> User Groups are available for organizations on the [Enterprise plan](https://www.langchain.com/pricing) and for [self-hosted](https://docs.langchain.com/langsmith/self-hosted.md) deployments. [Contact our sales team](https://www.langchain.com/contact-sales) to learn more.

## Access rules

In a workspace, a user's permissions are the sum of their own [workspace role](https://docs.langchain.com/langsmith/rbac.md#workspace-roles) and the role of each user group they belong to. [Access policies](https://docs.langchain.com/langsmith/abac.md) can come from those roles and from the user groups themselves. A matching deny policy applies first and blocks access, whatever the roles allow. For the evaluation order, refer to [How ABAC works with RBAC](https://docs.langchain.com/langsmith/abac.md#how-abac-works-with-rbac).

A user group's role applies only to members who belong to the workspace. Giving a user group access does not add anyone to the workspace. To give a user group member access, [add the user to the workspace](https://docs.langchain.com/langsmith/set-up-hierarchy.md#set-up-a-workspace) or [sync the user group from your identity provider](#sync-user-group-members-from-your-identity-provider).

## Before you begin

* Ensure that [RBAC](https://docs.langchain.com/langsmith/rbac.md) and [ABAC](https://docs.langchain.com/langsmith/abac.md) are enabled for your organization. Without ABAC, user group access policies have no effect.
* For self-hosted deployments, see below.

## Enable user groups for self-hosted deployments

> [!NOTE]
>
> On [self-hosted](https://docs.langchain.com/langsmith/self-hosted.md) deployments, user groups require LangSmith 0.18 or later.

Use one of the following options to enable user groups:

* **Enable for a specific organization**: Run the following against your LangSmith PostgreSQL database, replacing `<organization_id>` with the ID copied from the organization settings page in the UI:

  ```sql theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  UPDATE organizations SET config = config || '{"can_use_teams": true}' WHERE id = '<organization_id>' AND NOT is_personal;
  ```

* **Enable for all organizations**: Add the following environment variable to `commonEnv` in your `values.yaml`:

  ```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  DEFAULT_ORG_FEATURE_CAN_USE_TEAMS: "true"
  ```

To manage user groups in the UI, also [enable ABAC](https://docs.langchain.com/langsmith/abac.md#enable-abac-on-a-self-hosted-deployment).

## Create a user group

To create a user group:

1. Navigate to Organization **Settings** > **User Groups**.
2. Click **Create user group**.
3. Enter a **Name** and, optionally, a **Description**.
4. (Optional) Add members, workspace access, and access policies. Refer to [Edit a user group](#edit-a-user-group).
5. Click **Create user group**.

User group names must be unique across the organization.

## Edit a user group

To edit a user group:

1. Navigate to Organization **Settings** > **User Groups** and click the user group.
2. Make your changes in **Members**, **Workspaces**, or **Access policies**.
3. Click **Update user group**.

LangSmith saves the changes together. If one fails, LangSmith keeps the unsaved changes so you can retry them.

### Members

Click **+ Add member** to add organization members. To remove a member, click the remove icon on their row. A removed member loses the access the user group gave them.

The section also lists the user group's [workspace-only members](#add-workspace-only-members-and-policies), with a link to the workspace they were added in.

### Workspaces

Click **+ Grant workspace** and select a workspace to give the user group's members a role there. The role defaults to [Workspace Viewer](https://docs.langchain.com/langsmith/rbac.md#workspace-viewer). You can select any built-in or [custom workspace role](https://docs.langchain.com/langsmith/rbac.md#custom-roles) instead, and change it later on the workspace's row.

To remove access, click the remove icon on the workspace's row and type the workspace name to confirm. Removing access also removes the user group's workspace-only members and access policies in that workspace.

### Access policies

Click **+ Attach policy** to attach an [access policy](https://docs.langchain.com/langsmith/abac.md#access-policy-structure). The user group's access policies apply to its members in every workspace the user group can access.

To limit a user group's policy to one workspace, attach it through the [API](#manage-user-groups-with-the-api) with `workspace_id` set. The user group must have access to that workspace, and you must be a member of that workspace. The user group dialog shows the workspace that such a policy applies in.

## Add workspace-only members and policies

In a workspace that a user group can access, a [Workspace Admin](https://docs.langchain.com/langsmith/rbac.md#workspace-admin) can add members and access policies to the user group for that workspace only. This lets a workspace's administrators manage access in their workspace without organization-level permissions.

Workspace-only members do not receive the user group's role. They receive only the workspace-only access policies, and only in that workspace. Workspace-only access policies apply only to workspace-only members.

For example, the `Support` user group has the [Workspace Editor](https://docs.langchain.com/langsmith/rbac.md#workspace-editor) role in `Production`. A Workspace Admin in `Production` can add more users to `Support` for that workspace only, and attach a policy that lets them read projects tagged `Environment=Development`.

To add workspace-only members or policies:

1. Navigate to the workspace's **Settings** > **User Groups**. The page lists each user group with access to the workspace.
2. Click a user group.
3. Add or remove members, or attach or detach access policies.
4. Click **Update user group**.

You can add only users who are members of the workspace. The user group's name, description, members, and access policies appear as read-only.

## Delete a user group

To delete a user group, navigate to Organization **Settings** > **User Groups**, click the delete icon on the user group's row, and type the user group name to confirm.

Deleting a user group removes its members, workspace access, and access policies, including workspace-only members and policies.

A role that a user group uses in a workspace cannot be deleted. Change the user group's role or remove its workspace access first.

## Sync user group members from your identity provider

Link a user group to a group in your identity provider (IdP), and LangSmith sets the user group's members from that group. Sync works with [SCIM](https://docs.langchain.com/langsmith/user-management.md#set-up-scim-for-your-organization) and [SSO Groups Sync](https://docs.langchain.com/langsmith/user-management.md#sso-groups-sync-alternative). Workspace-only members are not synced.

To sync a user group:

1. Navigate to Organization **Settings** > **User Groups** and click the user group.
2. In **General**, enter the group's name in **IdP group**. For SCIM, enter the SCIM group's name. For SSO Groups Sync, enter a value from the [groups claim](https://docs.langchain.com/langsmith/user-management.md#sso-groups-sync-alternative).
3. Select **Sync members from the IdP group**.
4. Click **Update user group**.

### Sync behavior

* **Matching**: A group matches when its name equals the user group's IdP group, ignoring leading and trailing spaces. Matching is case-sensitive. Each IdP group can be linked to only one user group.

* **Timing**: SSO Groups Sync updates a user's memberships at each login and requires **Sync workspace/role assignments**. SCIM updates them when the user's SCIM groups change.

* **Membership**: A synced user group's members are the users in the IdP group. A change you make in LangSmith lasts until that user's next sync.

* **Organization role**: When no `LS:` group sets a user's organization role, a user group match sets it:

  * Through SSO Groups Sync, a new user joins the organization as an [Organization Viewer](https://docs.langchain.com/langsmith/rbac.md#organization-viewer). A user whose membership SSO Groups Sync manages is set to Organization Viewer. Other memberships, such as from an invite, keep their role.
  * Through SCIM, a user whose membership SCIM does not manage is set to [Organization User](https://docs.langchain.com/langsmith/rbac.md#organization-user), and SCIM manages the membership after that. This includes users with a higher role, such as Organization Admin.

* **Workspace membership**: Sync adds the user to each workspace the user group can access. This membership has no role of its own. The user's access comes from the user group's role. At the user's next sync, LangSmith removes the membership if no user group has access to that workspace.

* **Login gate**: When **Require matching group to sign in** is enabled, a group that matches a synced user group counts as a matching group. For SSO Groups Sync, this also requires **Sync workspace/role assignments**.

* **Sync disabled**: The user group keeps its members, and you manage them in LangSmith.

## Permissions

The minimum built-in role for each action:

| Action | Minimum built-in role |
| - | - |
| View user groups, members, and access policies | [Organization Viewer](https://docs.langchain.com/langsmith/rbac.md#organization-viewer) |
| Create, rename, or delete a user group | [Organization Operator](https://docs.langchain.com/langsmith/rbac.md#organization-operator) |
| Add or remove members | Organization Operator |
| Give, change, or remove workspace access | Organization Operator |
| Attach or detach access policies | Organization Operator |
| View workspace-only members and policies | [Workspace Viewer](https://docs.langchain.com/langsmith/rbac.md#workspace-viewer) |
| Add or remove workspace-only members and policies | [Workspace Admin](https://docs.langchain.com/langsmith/rbac.md#workspace-admin) |

[Custom roles](https://docs.langchain.com/langsmith/rbac.md#custom-roles) can hold the `workspaces:user-groups:*` permissions. For the permission each action checks, refer to the [operations reference](https://docs.langchain.com/langsmith/organization-workspace-operations.md#workspace-user-groups).

## Manage user groups with the API

The user group endpoints are under `/api/v1/platform/orgs/current/user-groups`. [Audit logs](https://docs.langchain.com/langsmith/audit-logs.md#tracked-operations-reference) record each change to a user group.

## See also

* [Role-based access control](https://docs.langchain.com/langsmith/rbac.md)
* [Attribute-based access control](https://docs.langchain.com/langsmith/abac.md)
* [User management](https://docs.langchain.com/langsmith/user-management.md)
* [Organization and workspace operations reference](https://docs.langchain.com/langsmith/organization-workspace-operations.md)
* [Audit logs](https://docs.langchain.com/langsmith/audit-logs.md)

***

[Connect these docs](https://docs.langchain.com/use-these-docs.md) to your agent of choice via MCP for real-time answers.

[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/user-groups.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
