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

# Groups

> Use identity-provider Groups as a source of Team membership

Groups contain people whose membership is managed by your identity provider (IdP) through a [SCIM directory](https://ryvn.ai/docs/connections/scim.md). Each Group records the directory that provisioned it, even after that directory is removed.

Manage Group names and membership in the IdP. Ryvn provides read-only inspection, not manual Group creation, renaming, or membership editing. There are no standalone Group CLI commands.

## View Groups

Open **Settings > Groups** in the organization receiving your provisioning data. Search by Group name, visible member names, or referencing Team names. Click a row to open its members and referencing Teams in a popup.

You need permission to read Groups. Member names and Team references also depend on your access to view people and Teams. An unavailable lookup is not proof that a Group has no members or no Team references.

## How Groups grant access

A Group supplies membership to a [Team](https://ryvn.ai/docs/guides/teams.md); the Team receives permissions through an access policy. Groups cannot be direct access-policy principals.

For example, to give members of an IdP Group named `Engineering` read access to a staging environment:

1. Provision the `Engineering` Group and its members through your SCIM directory.
2. In **Settings > Teams**, create or edit a Team named `staging-readers`. In **Members**, select the `Engineering` Group and save.
3. In **Settings > Access Policies**, add `staging-readers` as a Team member of a policy granting the viewer role on the staging environment.

The path is `Engineering` Group → `staging-readers` Team → access policy → staging access. Teams can also have direct people or service-user assignments. See [access-policy grants](https://ryvn.ai/docs/iac/access-policy#grants) for how roles and resource scopes fit together.

> [!NOTE]
>
> Removing a person from one Group removes that membership source, not every source of access. Direct Team assignments, other Groups, and other policies may still grant access.

## Names, mappings, and warnings

Teams declare Groups by exact display name, including capitalization and spaces. Ryvn also keeps a saved mapping to the resolved Group and its directory.

If you rename a Group in the IdP, a Team declaring its old name may show a resolution warning. The Team's Group chip can show the saved mapping alongside the declared name. A missing name or warning does not necessarily remove the saved mapping: the previously mapped Group can still contribute its current members. If no Group is mapped, the declaration contributes no members.

Review the declaration, saved mapping, and warning together. Update the Team to the intended Group name after an IdP rename. If a matching name later resolves to another Group in the same directory, the Team can map to that Group; the display-name declaration is not a permanent link to one Group. A replacement directory does not silently take over mappings from the original directory.

## Delete a retained Group

While the original directory exists, manage Group deletion in the IdP. After that directory is removed, Ryvn retains its Groups and membership rather than deleting them automatically.

To delete a retained Group, open **Settings > Groups**, use that Group's row menu, choose **Delete**, and confirm **Delete**. The option requires permission to delete that Group (`group.delete`) and permission to read integrations (`integration.read`), so Ryvn can confirm its original directory is gone. A lookup failure alone does not enable deletion. A different directory may already exist in the organization.

Deletion removes the selected Group and its memberships, clears saved mappings to it, and updates affected Team access. Teams keep their display-name declarations, which may become unresolved. It does not delete the people or remove their other access sources. Review referencing Teams before confirming.

## Troubleshooting

| Symptom | What to check |
| - | - |
| A Group is missing | Check the Ryvn organization, your Group-read access, and whether the IdP is configured to send Groups. Review its provisioning errors and [directory configuration](https://ryvn.ai/docs/connections/scim.md). |
| Provisioning reports a name conflict | Group names must be unique within the organization, ignoring capitalization. Retained Groups also reserve their names; review old Groups before deleting them or choosing another name in the IdP. |
| A member shows **Details unavailable** | Ryvn could not load the people lookup. Check your permissions and retry; this does not establish that the person is absent. |
| A member shows **Unavailable user** | No matching person was found in the visible people list. Check the organization and person in **Settings > People**, then the IdP's provisioning results. |
| A Team shows a Group warning | Check the exact declared name, saved mapping, and directory source. Renaming a Group or replacing a directory does not guarantee that the declaration now points where you intend. |
| **Delete** is missing | The original directory may still exist, or the permissions or directory lookup needed to establish deletion eligibility are unavailable. |