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

# Groups

> Create user groups manually in Ravenna or sync them from identity providers like Okta and Google Workspace to manage access and assignments.

User groups organize workspace members into collections for easier collaboration and management. Create groups manually or sync them automatically from identity providers like Google Workspace to coordinate work and manage access within your workspaces.

## Mental model

User groups are collections of organization members. They serve as reusable references for access control, workflow assignments, and form fields. Groups can be created manually or synced automatically from identity providers (Okta, Google Workspace, Slack).

Groups are organization-scoped. A group exists at the organization level. However, which groups appear in form fields depends on the workspace. Manually created groups only appear in workspaces they are assigned to. Groups synced from identity providers (Okta, Google Workspace, Slack) appear in all workspaces.

***

## Manual vs synced groups

| Aspect | Manual groups | Synced groups |
| - | - | - |
| **Source** | Created in Ravenna | Imported from IdP (Okta, Google Workspace, Slack) |
| **Membership management** | Edited directly in Ravenna | Managed in the IdP, synced to Ravenna |
| **Membership editing in Ravenna** | Yes | No (read-only in Ravenna) |
| **Sync behavior** | N/A | Automatic membership updates from IdP |
| **Source indicator** | None | Shows source integration |

Both types can be used identically in access levels, workflows, forms, and custom fields.

***

## Groups in the platform

**Access level mapping**: Groups map to access levels on applications. When a user is granted access at a specific level, they can be added to the corresponding IdP group via workflow actions, enabling automated provisioning.

**Workspace membership**: Groups can grant membership in a workspace. A workspace's General settings hold two grant lists, member groups and admin groups, and Ravenna derives that workspace's member list from them. A group can appear on one list or the other, not both, and a user covered by both lists through different groups gets admin. Memberships created this way are marked group managed and are re-derived whenever the grants change, whenever a granting group's membership changes during an identity provider sync, when a granting group is deleted, and when the integration behind a granting group is disconnected. Users who are not organization members are skipped; blocked organization members are still granted membership, since blocking gates sign-in rather than group membership. Grants raise or confirm a role, never lower one granted by hand: a manual member whose own role outranks every grant covering them keeps that role and stays manual, so an admin added directly is not demoted by a member group.

**Organization admin**: Groups can grant the organization admin role. Organization General settings hold one grant list, admin groups, and Ravenna derives the organization's admin roster from it. Admin roles created this way are marked group managed and are re-derived whenever the grants change, whenever a granting group's membership changes during an identity provider sync, when a granting group is deleted, and when the integration behind a granting group is disconnected. The sync-driven reconcile runs after the group sync phase and is skipped when that phase errored, since acting on half-synced membership would demote every admin the organization has. Users in a granting group who are not organization members are skipped, and guests and bots never receive admin from a group. Dropping a group demotes the admins it granted to member rather than removing them from the organization.

**Workflow approvers**: Assign a group as the approver pool for workflow approval steps. Any member of the group can approve.

**Ticket approval rounds**: Select user groups when creating approval rounds on tickets. Groups are immediately expanded into individual users server-side when saved, unlike approval templates which persist group IDs. This maintains the existing approval round behavior where only concrete users are stored as approvers.

**Form fields**: The "User group select" custom field type lets requesters select a group when creating a ticket. Admins can configure an **allowlist** on the field to restrict which groups appear as options, and optionally filter groups by **source** (e.g., only Okta groups or only Ravenna-native groups). These constraints are enforced in both the form UI and the agent tool when the agent resolves groups conversationally.

**Form audience access control**: Groups can define form audiences. When a form's audience type is set to "Specific" (User Groups), only members of the selected groups can see and submit that form. This filtering is server-side and applies to the Portal, Slack form selection, and ticket creation flows.

**Agent rules**: Groups can be referenced in agent rules when the agent needs to identify team membership or route requests. The <Tooltip headline="Group Lookup" tip="Agent tool that searches groups by name, description, email, and metadata" cta="Configure agent tools" href="/documentation/automate/agents/configure#group-lookup-behavior">Group Lookup</Tooltip> tool respects workspace visibility, allowlist, and source constraints configured on form fields.

**Mentions in messages and workflow forms**: Groups appear alongside people in the `@` mention picker in ticket replies, private notes, message edits, the agent editor, and rich-text workflow form fields. In agent rules, a `[user_group: id=<id>, name='<name>']` bracket reference tells the agent to write the token `@group[<name>](<id>)` in its response, which renders as a native group mention. When the message is dispatched to Slack and the group is a Slack subteam synced from that same workspace (matching `teamId`), Ravenna substitutes a real `<!subteam^ID>` ping; otherwise the mention degrades to a plain `@handle` or `@name` on Slack, email, and web.

***

## Constraints and gotchas

* Group names must be unique within the organization.
* Synced group membership cannot be edited in Ravenna. Changes must be made in the source identity provider.
* Groups are organization-scoped, but their visibility in user group select fields is workspace-aware. Manually created groups only appear in workspaces they are assigned to, while synced groups are visible across all workspaces.
* Synced groups appear alongside manual groups in the UI with a source indicator.
* Google Workspace groups are searchable by email address and by alias. Alias search is an exact, case-insensitive match on the full address, while name and email search match partial text.
* When **Include App Groups** is off on the Okta integration, Ravenna does not sync Okta app groups (type `APP_GROUP`). App groups that were already synced are archived on the next sync, not deleted. Archived groups are excluded from pickers but still resolve in existing references, where they display as "(Archived)". Turning the setting back on unarchives them on the next sync.
* Multiple identity providers can sync groups simultaneously. Okta groups, Google Workspace groups, and Slack user groups can all coexist.
* Workspace memberships granted by a group are group managed. They cannot be removed, and their role cannot be changed, from the workspace **Members** page or a member's detail page. Change the workspace's group grants instead. A membership added by hand becomes group managed once a granting group grants that user the same role or a higher one.
* A hand-added membership the grants would demote is left alone, role and all, and stays manual. Lowering it takes a manual role change on the **Members** page, after which the next re-sync adopts the membership. This is the one case where the workspace roster can disagree with the groups by design.
* Deleting a group removes the workspace memberships it granted, unless another granting group still covers the same user. Bot members are never added, removed, or re-roled by group grants.
* Organization admin roles granted by a group are group managed too. The role cannot be changed from the organization **Members** page or a member's detail page, but the member can still be removed from the organization, since the grant decides the role and nothing else.
* A group can grant organization admin and workspace membership at the same time. The two grant lists are independent, so removing a group from one does not change the other.
* Deleting a group that is referenced in access levels, workflows, or forms may break those references.
* When duplicating a form across workspaces, any allowlist and source filter configured on user group select fields are stripped because group IDs may differ between workspaces.


## Related topics

- [Create a user group](/api/user-group/create-a-user-group.md)
- [Delete a user group](/api/user-group/delete-a-user-group.md)
- [Get a user group](/api/user-group/get-a-user-group.md)
- [Update a user group](/api/user-group/update-a-user-group.md)
- [Delete multiple user groups](/api/user-group/delete-multiple-user-groups.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.