> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
# User groups
> Assign permissions to users in bulk with user groups.
**Organization Admin** permissions are required to manage user groups.
User groups let you manage permissions for multiple users at once instead of configuring each user individually.
## Creating user groups
User groups can also be created through some [SCIM integrations](/administration/authentication).
1. Navigate to **Settings > Groups**.
2. Click **New Group**.
3. Enter a **Name** for the group. You can also add a description.
4. Click **Save** to create the group.
After the group is created, you'll be redirected to the group's **Members** tab where you can [add users](#adding-users-to-groups).
Use the [Create user group API](/api/user-groups/create-user-group) API to programmatically create a user group:
```http theme={null}
curl --request POST \
--url https://{your-omni-org}.omniapp.co/api/scim/v2/groups \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '
{
"displayName": "Blob Sales",
"members": [
{
"value": "9e8719d9-276a-4964-9395-a493189a247c"
}
]
}
'
```
## Managing group members
Users can be added to and removed from groups manually, through the [API](/api/user-groups) or some [SCIM integrations](/administration/authentication).
You can add [external users](/administration/users/external-users) to groups and remove them only in the Omni UI, not through the API or SCIM. API group responses do not include external users.
### Adding users to groups
A user's group membership is also available as the `omni_user_groups` [user attribute](/administration/users/attributes#default-system-user-attributes), which can be used for data-level permissioning.
You can add users to groups from the group's **Members** tab or directly from a [user's **Groups** tab](#user-profile-group).
From a group's **Members tab**:
1. Navigate to **Settings > Groups**.
2. Click the group you want to work with.
3. In the group's **Members** tab, click **Add Members**.
4. Search for and select users in the modal, then click **Add**.
Use the [Update user group](/api/user-groups/update-user-group) API to programmatically add users to a user group:
```http theme={null}
curl --request PATCH \
--url https://{your-omni-org}.omniapp.co/api/scim/v2/groups/{userGroupId} \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"display": "blob.ross@blobsrus.co",
"value": "9e8719d9-276a-4964-9395-a493189a247c"
}
]
}
]
}
'
```
### Removing users from groups
When a user is removed from a group, they lose any [permissions that were granted through that group](#assigning-permissions-to-groups). Users can be re-added as group members if needed.
You can remove users from groups from the group's **Members** tab or directly from a [user's **Groups** tab](#user-profile-group).
From a group's **Members tab**:
1. Navigate to **Settings > Groups**.
2. Click the group you want to work with.
3. In the group's **Members** tab, locate the user you want to remove.
4. Click **Remove from group**.
Use the [Update user group API](/api/user-groups/update-user-group) to programmatically remove a user from a group:
```http theme={null}
curl --request PATCH \
--url https://docs.omniapp.co/api/scim/v2/groups/{userGroupId} \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "remove",
"path": "members[value eq \"9e8719d9-276a-4964-9395-a493189a247c\"]"
}
]
}
'
```
Managing a user's groups from their settings
In addition to managing user memberships from the group's **Members** tab, you can view and modify an individual user's group memberships from their [user settings](/administration/users/settings).
This is particularly useful when managing a user who is not yet a member of any groups, or when you need to modify multiple group memberships for a single user.
## Assigning permissions to groups
Access to connections, models, and content can be granted to an entire user group at once.
Assigning connection/model access
Model roles control what actions user group members can perform on connections and the individual models associated with those connections.
Group roles are combined with any roles a user has directly or through the connection's base access, and Omni grants the most permissive one. Adding a user to a group can raise their access but can't lower it. User groups grant connection and model roles only; the **Organization Admin** role is assigned per user. Refer to [Connection permission basics](/administration/users/permissions#connection-permission-basics) for more information.
1. Navigate to **Settings > Connections** and open the connection you want to work with.
2. Click the **Permissions** tab and scroll to **Connection Roles**.
3. In the **Groups** view, locate the group you want to grant permissions to.
4. Use the **Access** dropdown to change the group's role. If [custom roles](/administration/users/custom-roles) are defined, they will display as options in the dropdown.
Use the [Assign or update user group model role API](/api/user-group-model-roles/assign-or-update-user-group-model-role) to programmatically assign model roles to user groups. The role will apply to all members of the group.
```https theme={null}
curl --request POST \
--url https://blobsrus.omniapp.co/api/v1/user-groups/{userGroupId}/model-roles \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '
{
"connectionId": "bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed",
"modelId": "7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
"roleName": "QUERIER"
}
'
```
### Assigning content access
To grant access to documents and folders, share the content with the group. See [Content sharing](/share#users-and-user-groups) for details.
## Allowing groups to switch user attribute values
The **Allowed user attribute values** section of a group's **Settings** tab lists the [user attribute](/administration/users/attributes) values that group members can switch to in documents and the model IDE, if they have access.
See [User-selected attribute values](/administration/users/attributes/user-selected) to learn more about provisioning values.
## Deleting user groups
Deleting a user group is not reversible. Group members will lose any connection roles and content access that were granted through the group.
1. Navigate to **Settings > Groups**.
2. Click the icon in the user group's row.
3. When prompted, click **Yes, Delete** to confirm.
You can also delete a group by opening its **Settings** tab and clicking the **Delete** button.
Use the [Delete user group API](/api/user-groups/delete-user-group) to programmatically delete a user group:
```http theme={null}
curl --request DELETE \
--url https://{your-omni-org}>.omniapp.co/api/scim/v2/groups/{userGroupId} \
--header 'Authorization: Bearer {token}'
```
## Next steps
* [Custom roles](/administration/users/custom-roles) - Define custom role variations to assign to groups
* [Content sharing](/share) - Learn how to share documents and folders with users and groups
* [Permissions](/administration/users/permissions) - Understand how connection roles and permissions work
* [User-selected attribute values](/administration/users/attributes/user-selected) - Let group members switch their own attribute values
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.