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.

Groups page showing a list of user groups with their name, label, member count, and group ID — Settings > Groups page in Omni, listing all user groups

Creating user groups

User groups can also be created through some SCIM integrations.

Omni UI
API

Navigate to Settings > Groups.
Click New Group.
Enter a Name for the group. You can also add a description.
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.

Use the Create user group API API to programmatically create a user group:

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 or some SCIM integrations.

You can add 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, which can be used for data-level permissioning.

Omni UI
API

You can add users to groups from the group’s Members tab or directly from a user’s Groups tab.From a group’s Members tab:

Navigate to Settings > Groups.
Click the group you want to work with.
In the group’s Members tab, click Add Members.
Search for and select users in the modal, then click Add.

Use the Update user group API to programmatically add users to a user group:

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. Users can be re-added as group members if needed.

Omni UI
API

You can remove users from groups from the group’s Members tab or directly from a user’s Groups tab.From a group’s Members tab:

Navigate to Settings > Groups.
Click the group you want to work with.
In the group’s Members tab, locate the user you want to remove.
Click Remove from group.

Use the Update user group API to programmatically remove a user from a group:

curl --request PATCH \
  --url https://docs.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": "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. 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 for more information.

Omni UI
API

Navigate to Settings > Connections and open the connection you want to work with.
Click the Permissions tab and scroll to Connection Roles.
In the Groups view, locate the group you want to grant permissions to.
Use the Access dropdown to change the group’s role. If custom roles are defined, they will display as options in the dropdown.

Connection Roles section showing groups listed with their model, access level dropdown, and member count — Connection Roles section showing the Groups view with access dropdowns for each group

Use the Assign or update user group model role API to programmatically assign model roles to user groups. The role will apply to all members of the group.

curl --request POST \
  --url https://blobsrus.omniapp.co/api/v1/user-groups/{userGroupId}/model-roles \
  --header 'Authorization: Bearer <token>' \
  --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 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 values that group members can switch to in documents and the model IDE, if they have access. See User-selected attribute values 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.

Omni UI
API

Navigate to Settings > Groups.
Click the icon in the user group’s row.
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 to programmatically delete a user group:

curl --request DELETE \
  --url https://{your-omni-org}>.omniapp.co/api/scim/v2/groups/{userGroupId} \
  --header 'Authorization: Bearer {token}'

Next steps

Custom roles - Define custom role variations to assign to groups
Content sharing - Learn how to share documents and folders with users and groups
Permissions - Understand how connection roles and permissions work
User-selected attribute values - Let group members switch their own attribute values

Connect data

Manage users and permissions

Manage organization

Identity Providers

Security

Monitor Omni

Creating user groups

Managing group members

Adding users to groups

Removing users from groups

Managing a user’s groups from their settings

Assigning permissions to groups

Assigning connection/model access

Assigning content access

Allowing groups to switch user attribute values

Deleting user groups

Next steps

​Creating user groups

​Managing group members

​Adding users to groups

​Removing users from groups

​Managing a user’s groups from their settings

​Assigning permissions to groups

​Assigning connection/model access

​Assigning content access

​Allowing groups to switch user attribute values

​Deleting user groups

​Next steps

Creating user groups

Managing group members

Adding users to groups

Removing users from groups

Managing a user’s groups from their settings

Assigning permissions to groups

Assigning connection/model access

Assigning content access

Allowing groups to switch user attribute values

Deleting user groups

Next steps