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

# Groups

> Organize users and manage permissions at scale

Groups let you assign roles to multiple users at once. Add users to a group, and they automatically inherit all roles assigned to that group.

## How to Create a Group

<Steps>
  <Step title="Open Groups Page">
    Go to **Access Management → Groups** and click **Create Group**.
  </Step>

  <Step title="Enter Group Details">
    * **Group Key** (required): Unique identifier (lowercase, dashes allowed). Cannot be changed later.
    * **Display Name** (required): Friendly name shown in the UI.
    * **Description** (optional): Explain the group's purpose.
  </Step>

  <Step title="Assign Initial Roles (Optional)">
    Select roles that all group members should have. You can modify this later.
  </Step>

  <Step title="Save">
    Click **Create Group**. You can now add members.
  </Step>
</Steps>

## How to Assign Roles to a Group

<Steps>
  <Step title="Open Group">
    Go to **Access Management → Groups** and click on the group.
  </Step>

  <Step title="Go to Roles Tab">
    Click the **Roles** tab.
  </Step>

  <Step title="Select Roles">
    Check the roles you want to assign. All group members will inherit these roles.
  </Step>

  <Step title="Save">
    Click **Save Changes**. Permissions take effect immediately for all members.
  </Step>
</Steps>

<Info>
  When you add or remove roles from a group, all members' permissions update immediately.
</Info>

## How to Add Members to a Group

<Steps>
  <Step title="Open Group">
    Go to **Access Management → Groups** and click on the group.
  </Step>

  <Step title="Go to Members Tab">
    Click the **Members** tab, then click **Add Member**.
  </Step>

  <Step title="Select User">
    Search for a user by name or email and select them.
  </Step>

  <Step title="Confirm">
    Click **Add Member**. The user immediately gains all roles assigned to the group.
  </Step>
</Steps>

<Tip>
  You can also manage group memberships from a user's profile page (Groups tab).
</Tip>

## How to Remove Members from a Group

On the group's **Members** tab, click the remove icon on the member's card.

<Warning>
  Removing a member immediately revokes all permissions they inherited from this group.
</Warning>

## How to Delete a Group

<Steps>
  <Step title="Open Group">
    Go to **Access Management → Groups** and click on the group.
  </Step>

  <Step title="Delete">
    Scroll to the **Danger Zone** section and click **Delete**.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  Deleting a group removes all members and revokes any permissions they inherited solely from this group.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="User doesn't have expected permissions">
    1. Check if the user is in the group (Members tab)
    2. Check if the group has the correct roles (Roles tab)
    3. Verify those roles include the required permissions
  </Accordion>

  <Accordion title="Cannot add user to group">
    * User must be a member of your organization first (invite them)
    * User may already be in the group
  </Accordion>

  <Accordion title="Group key already exists">
    Keys must be unique. Try: `dev-team-2`, `frontend-devs`, `k8s-admins`
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between groups and roles?">
    **Roles** define permissions (what you can do). **Groups** organize users and assign roles collectively (who you are).
  </Accordion>

  <Accordion title="Can a user be in multiple groups?">
    Yes. Permissions from all groups are combined with any direct role assignments.
  </Accordion>

  <Accordion title="Can I change a group key after creation?">
    No. The key is permanent. You can change the display name anytime.
  </Accordion>

  <Accordion title="What happens when I remove a role from a group?">
    All members immediately lose that role's permissions (unless they have it from another source).
  </Accordion>

  <Accordion title="What happens when I delete a group?">
    All members are removed and lose permissions inherited from that group. Other permissions remain intact.
  </Accordion>
</AccordionGroup>