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

# Manage User Groups

> Create user groups, add team members, and choose which restricted datasets and environments each group can read

EntBeta

> [!NOTE]
>
> Dataset restrictions are in public [beta](https://docs.honeycomb.io/troubleshoot/product-lifecycle/release-stages.md#beta) on the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/).

User groups are how team members get access to restricted datasets and environments.
Team Owners manage groups in the **User Groups** view of **Team Settings**, which lists each group's name, description, and member count.
A team can have up to 50 user groups.
To learn how groups and restrictions work together, visit [What are dataset restrictions?](https://docs.honeycomb.io/configure/teams/dataset-restrictions).

You can also manage user groups with the Honeycomb API and a Management Key that has the `groups:read` or `groups:write` scope.
To learn more, visit [Management Key Scopes](https://docs.honeycomb.io/configure/teams/manage-api-keys.md#management-key-scopes).
To automate groups and restrictions, visit [Manage Dataset Restrictions with the API](https://docs.honeycomb.io/configure/teams/dataset-restrictions/manage-with-api.md).

## Before you begin

You must be a [Team Owner](https://docs.honeycomb.io/configure/teams/manage-permissions.md) to view and manage user groups.

## Create a user group

Create a user group for each set of people who need the same access to restricted data.

To create a user group:

1. Select **Account** from the navigation menu, and choose **Team Settings**.

2. Select the **User Groups** view.

3. Select **New group**.

4. On the **Create New Group** page, enter a **Group name** and, optionally, a **Group description**.
   Group names must be unique within your team.

5. In the **Permissions** section, select the group's **Dataset access** for each environment.
   Optionally, in the **Users** section, select **Add users**, select the team members who belong to the group, and then select **Add *N* users**.

6. Select **Create group**.

The new group appears in the **User Groups** list, and within a minute its members can read the restricted data you granted it.

## Grant a group access to restricted data

Grant access so group members can read restricted data; everyone on your team can already read unrestricted datasets.

To grant a group access to restricted data:

1. Select **Account** from the navigation menu, and choose **Team Settings**.

2. Select the **User Groups** view.

3. Locate the group in the list, and select **Edit**.

4. In the **Permissions** section, locate the environment in the table.

5. In the **Dataset access** column, select the group's access:

   | Environment | Option | Group members can read |
   | - | - | - |
   | Restricted | **Allow all** | Every dataset in the environment. |
   | Restricted | **Deny all** | No datasets in the environment. |
   | Unrestricted | **Allow all** | Every dataset in the environment, including restricted datasets and datasets created later. |
   | Unrestricted | **Unrestricted datasets only** | Only the environment's unrestricted datasets. This option is the default. |
   | Unrestricted | **Custom** | The environment's unrestricted datasets, and the restricted datasets you choose. |

6. If you selected **Custom**, in the **Customize access to restricted datasets** dialog, select the restricted datasets the group can read, and then select **Allow access to *N* restricted datasets**.
   The datasets you chose appear in the **Allowed restricted datasets** column.
   To change them later, select **Edit** in that column.

7. Select **Update group**.

Within a minute, group members can read the restricted data you granted.

If an environment has no restricted datasets, **Dataset access** shows **Allow all** and can't be changed.
Every dataset in that environment is already readable, so Honeycomb saves no access for the group, and group members can't read a dataset you restrict there later.
After you restrict the first dataset in the environment, edit the group, select **Allow all** again, and select **Update group**.

> [!WARNING]
>
> Setting **Environment access** to **Restricted** restricts the environment for your whole team, not only for this group.
> It also turns off the individual restriction on each of the environment's datasets.
> If you later set the environment back to **Unrestricted**, every dataset in it becomes unrestricted.
> Changing **Environment access** in either direction clears this group's **Dataset access** for that environment, so set it again before you save.
> To learn more, visit [Restrict an environment](https://docs.honeycomb.io/configure/teams/dataset-restrictions/restrict-access.md#restrict-an-environment).

System environments, except S3 Archive environments, can't be restricted, so everyone keeps access to them.

## Add users to a group

A person's access is the combination of every group they belong to, so add them to each group whose access they need.

To add users to a group:

1. Select **Account** from the navigation menu, and choose **Team Settings**.

2. Select the **User Groups** view.

3. Locate the group in the list, and select **Edit**.

4. In the **Users** section, select **Add users**.

5. Select the users to add, and then select **Add *N* users**.

6. Select **Update group**.

Within a minute, the users you added can read everything the group has access to.
Team Owners can read every dataset whether or not they belong to a group.

## Remove users from a group

Remove users from a group when they no longer need its access.
They keep any access that their other groups grant.

To remove users from a group:

1. Select **Account** from the navigation menu, and choose **Team Settings**.

2. Select the **User Groups** view.

3. Locate the group in the list, and select **Edit**.

4. In the **Users** section, select the users to remove, and then select **Remove users from group**.

5. In the confirmation dialog, select **Remove *N* users**.

6. Select **Update group**.

Within a minute, the users you removed lose the access this group granted, unless another group grants it.
When someone leaves your team, Honeycomb removes them from all of the team's user groups.

## Edit a user group

Edit a group when its name, description, permissions, or members no longer fit how your team uses it.

To edit a user group:

1. Select **Account** from the navigation menu, and choose **Team Settings**.

2. Select the **User Groups** view.

3. Locate the group in the list, and select **Edit**.

4. Make your changes.

5. Select **Update group**.

Within a minute, your changes apply to every member of the group.
If you select **Cancel** with unsaved changes, Honeycomb asks whether to keep editing, discard your changes, or update the group.

## Delete a user group

Delete a group when nobody needs its access anymore.
Its members lose the access it granted, unless another group also grants that access.
Deleting a group doesn't remove any dataset or environment restrictions.

To delete a user group:

1. Select **Account** from the navigation menu, and choose **Team Settings**.

2. Select the **User Groups** view.

3. Locate the group in the list, and select **Delete**.

4. In the **Delete user group?** dialog, enter the group's name to confirm.

5. Select **Delete group**.

The group no longer appears in the **User Groups** list, and within a minute its members lose the access it granted.

## Troubleshooting

When access doesn't match what you set up, check these common causes.

### A group member can't read a dataset I granted access to

Group access is set separately for each environment, so start with the environment that holds the dataset.

* If the group uses **Custom**, check that the dataset appears in the **Allowed restricted datasets** column for that environment.
* If someone changed **Environment access** for that environment, the group's **Dataset access** was cleared.
  Set it again, and select **Update group**.
* If you set **Dataset access** to **Allow all** while the environment had no restricted datasets, Honeycomb saved no access, because there was nothing to grant.
  Edit the group, select **Allow all** again, and select **Update group**.

### A restricted user can still get restricted data

Some access paths don't depend on a person's user groups.

* Configuration Keys aren't subject to dataset restrictions, so anyone with a key can read every dataset its permissions cover.
  Honeycomb hides an environment's keys from people who can't read every dataset in it, and hides team-wide keys from people who can't read every dataset on the team.
* Some downloads, Canvas investigations, Findings, and Honeycomb MCP tools don't check dataset restrictions.
  For the list, visit [Limits and known limitations](https://docs.honeycomb.io/configure/teams/dataset-restrictions#limits-and-known-limitations).

## Next steps

To continue configuring dataset restrictions, visit these pages:

* [Restrict Access to Datasets and Environments](https://docs.honeycomb.io/configure/teams/dataset-restrictions/restrict-access.md)
* [What Restricted Users Can Do](https://docs.honeycomb.io/configure/teams/dataset-restrictions/restricted-user-actions.md)
* [Manage Dataset Restrictions with the API](https://docs.honeycomb.io/configure/teams/dataset-restrictions/manage-with-api.md)
* [Investigate group changes in the Activity Log](https://docs.honeycomb.io/configure/teams/investigate-activity.md#groups)
