# Groups

Groups are the primary organizing unit for access control in the vault. Administrative Policy and Signing Policy both reference groups when specifying who can perform an action or initiate a signing request. Set up your groups before configuring policies.

## What a group is

A group is a named collection of vault identities. It can contain human users, machine users and agents, or a mix of both. Groups are flat: there is no nesting, and a group cannot contain another group. A user can belong to multiple groups simultaneously and gains the combined capabilities of all of them.

Groups have three attributes: a display name (unique within the vault), an optional description, and a membership list.

## Create a group

You need the **Manage User Groups** capability to create groups.

1. Navigate to **Users & Groups** in the sidebar. The page opens on the **Groups** tab by default.
2. Click **Create New** in the top-right corner and select **Create Group** from the dropdown.
3. The **Create Group** modal opens. Enter:
   * **Group name** (required): the name must be unique across the vault.
   * **Description** (optional): a note about the group's purpose.
   * **Members** (optional at creation): search for and select users from the multi-select list. You can also add members after the group is created.
4. Click **Create**. A success toast appears and the new group appears in the list.

{/* TODO screenshot: The Create Group modal with the group name field filled in, an optional description field, and a multi-select member search list showing a few selected users. */}

## View and filter groups

The Groups tab displays all groups in a table. Use the filters at the top to narrow the list:

* **Name search**: find groups by name substring.
* **Member filter**: show only groups that contain a specific user.

![Groups tab listing all user groups with member avatars and counts](/img/guide/users-groups/groups-list.png)
*The Groups tab. Each group shows its description, members, and audit metadata.*

## Edit a group

1. Find the group in the list.
2. Click the row actions dropdown (the three-dot menu at the end of the row) and select **Edit**.
3. The edit modal lets you update the group name, description, and membership (add or remove members).
4. Click **Save**. The change takes effect immediately.

## Add and remove members

You can manage membership from the edit modal described above. There is no separate membership page.

* To **add members**: in the edit modal, type in the member search field and select users from the dropdown.
* To **remove members**: click the remove icon next to a member's name in the list.

Changes to group membership are reflected immediately in policy evaluation for subsequent requests.

## Delete a group

:::warning\[Policy impact]
Deleting a group removes it from any Administrative Policy or Signing Policy rules that reference it. Review your policies after deleting a group to avoid leaving actions without a permitted group. An action with no permitted groups becomes deny-by-default for everyone.
:::

To delete a group:

1. Select the checkbox to the left of the row (or multiple rows for a bulk delete).
2. Click the **Delete** button that appears in the bulk-action bar, or use the row actions dropdown for a single group.
3. Confirm the deletion in the dialog.

## How groups connect to policies

Once a group exists, you can reference it in:

* **Administrative Policy**: grant the group the ability to perform specific administrative actions. See [Configure your admin policy](/guide/admin-policy/configure).
* **Signing Policy**: restrict which groups can initiate signing requests for which keys. See [Understanding signing policies](/guide/signing-policy/understanding).

A group with no policy rules has no effective permissions. Creating a group alone does not grant any capability; the policy must reference it explicitly.