# Groups

## Overview

A **Group** is a named collection of users that share the same workspace permissions.

Instead of assigning workspace access user by user, you define it once on the group. Every member inherits it automatically.

Groups are managed in **Settings → Groups**.

Read [Users](https://ask.birdie.ai/admin-and-settings/users) first for the core concepts behind roles, workspace permissions, and permission resolution.

### What groups control

Groups control **workspace access** only.

They do **not** control roles.

This means two users in the same group can see the same workspaces but still have different feature access if their roles differ.

### When to use groups vs. individual access

| Scenario                                               | Recommendation                    |
| ------------------------------------------------------ | --------------------------------- |
| A team of 5+ users needs the same workspace access     | **Use a group**                   |
| One user needs one-off access to a specific workspace  | **Use individual access**         |
| New hires should be assigned automatically through SSO | **Use a group with SSO mappings** |
| A temporary contractor needs limited access            | **Use individual access**         |

## Viewing groups

The groups list gives a quick view of each group’s setup.

You can typically review:

* group name
* member count
* workspace count
* whether SSO mappings are enabled

Empty groups are allowed. This is useful when you want to prepare access before users are added.

## Creating a group

{% stepper %}
{% step %}

### Open Groups

Go to **Settings → Groups** and click **Create group**.
{% endstep %}

{% step %}

### Add basic details

Enter the group name and, if needed, a short description.
{% endstep %}

{% step %}

### Configure workspace access

Enable the workspaces this group should access, then set each permission level:

* **Viewer**
* **Editor**
* **Admin**
  {% endstep %}

{% step %}

### Finish setup

Create the group, then continue with member assignment or SSO mappings.
{% endstep %}
{% endstepper %}

## Adding members

After creating the group, add users to it so they inherit its workspace permissions.

You can also manage group membership from the user detail page in **Settings → Users**.

## SSO auto-assignment

Groups can assign users automatically based on Identity Provider attributes.

This is useful when access should follow department, region, business unit, or another IdP field.

### How SSO mappings work

1. Open the group.
2. Go to the **SSO Mappings** tab.
3. When a user logs in with SSO, Birdie evaluates the role sent.
4. Matching users are added to the group automatically.

### Important SSO mapping behavior

* Rules are evaluated on each login.
* All conditions must match.
* Matching is case-sensitive.
* Users added through SSO can still be removed manually if needed.

## How group permissions affect users

### Members inherit workspace access

Every user in the group receives the group’s workspace permissions automatically.

### Highest group permission wins

If a user belongs to multiple groups, the highest workspace permission wins for that workspace.

See [Users](https://ask.birdie.ai/admin-and-settings/users) for the full permission resolution rules.

### Direct user permissions still override groups

If a user also has a direct workspace assignment, that direct assignment takes precedence over the group.

### Deleting a group removes inherited access

If you delete a group, users lose any access that came only from that group.

If they have no other access source, their visible workspace list may become empty.

## Troubleshooting

**SSO mapping is not assigning users automatically.**

Check that attribute names and values match your IdP exactly. Matching is case-sensitive. Users may need to log out and back in.

**A user is in two groups with different access levels.**

The highest group permission wins for that workspace.

**I deleted a group by mistake.**

Groups cannot be recovered. Recreate the group and reassign its workspace permissions.