> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/admin-and-settings/users/groups.md).

# 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](/admin-and-settings/users.md) 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](/admin-and-settings/users.md) 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ask.birdie.ai/admin-and-settings/users/groups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.