The steps below explain how to list the existing user groups for a company, view the members of a specific group, and add a new user to that group.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| List user groups for company | POST /v3/companies/{companyId}/user-groups/list | List all available user groups for a company. You can use search text, filters, and sorting to narrow down results. URL path requires: companyId.Request body requires: pagination (with offset and limit). Optionally, provide searchText for case-insensitive search, sortParams to sort by NAME or CREATED_AT, and filters to filter by specific userGroupIds.Response will contain: userGroups (an array of user group objects each containing a unique id, name, and a description).Other APIs will use: userGroups > id (referred to as groupId in subsequent steps). | |
| Get user group | GET /v3/companies/{companyId}/user-groups/{groupId} | View the details of a specific user group selected from Step 1. This step is useful for confirming the group's name, description, and whether it is modifiable before proceeding. URL path requires: companyId and groupId (both as path parameters).Response will contain: the full user group object including id, name, description, companyId, isUnmodifiable, createdAt, updatedAt, createdBy, and updatedBy.Note: If isUnmodifiable is true, the group is platform-created and its name, description, and assigned roles cannot be changed. However, user members can still be added to it or removed from it.Other APIs will use: groupId from this response. | |
| List user group members | POST /v3/companies/{companyId}/user-groups/{groupId}/members | View the current members of the user group selected in Step 2. Use this step to verify existing members before adding a new user. URL path requires: companyId and groupId.Response will contain: members (an array of member objects each containing userId and addedAt) and pagination with totalNumResults.Note: Use this response to confirm that the user you intend to add is not already a member of the group. | |
| List user group roles (optional) | POST /v3/companies/{companyId}/user-groups/{groupId}/roles | View the roles currently assigned to the user group. This helps you understand what permissions the new user will inherit once added to the group. URL path requires: companyId and groupId from Step 1.Response will contain: roles (an array of role objects each containing role details with id, name, description, isPlatformRole, permissions, and associated scope information). | |
| Update user group members | PATCH /v3/companies/{companyId}/user-groups/{groupId}/members | Add the new user to the user group. URL path requires: companyId and groupId.Request body requires: userIdsToAdd (an array of user IDs to add to the group).Note: Users being added must belong to the same company as the user group. Once added, they will automatically inherit all roles and scopes assigned to the group. Response will contain: a 200 status code confirming the members were updated successfully. | |
| List user groups for user (optional) | POST /v3/users/{userId}/user-groups | Verify that the user was successfully added by listing all user groups the user belongs to. URL path requires: userId.Response will contain: userGroups (an array of user group objects that the user is a member of). The user group from Step 2 should now appear in this list, confirming the user has been successfully added and has inherited the group's roles and scopes. |