User groups Use this resource to create, update, and delete user groups.
Use the userGroups resource along with the users and roles resources to manage user privileges. Users and groups can perform tasks and access assets based on the roles that you assign to them.
You can send the following requests:
• • • • Note: This resource uses a dynamic rate limit. When the system experiences a large volume or size of requests, responses might be slow or fail with the error message, "too many requests."
For information about using the users and roles REST API resources, see the following topics:
For general information about users, user groups, and roles, see the Administrator help.
Note: The number of users, user groups, and roles combined cannot exceed 1000 for an organization.
Getting user group details You can request the details for all user groups in the organization or request the details for a particular user group.
GET request You can request the details for all user groups in the organization or request the details for a particular user group.
To get user group details, use the following URI:
/public/core/v3/userGroups
To get the details for a particular user group, you can include the following query parameters in the URI:
Parameter
Type
Description
q
String
Query filter. You can filter using one of the following fields:
- - limit
Int
Maximum number of user groups to return.
Default is 100.
skip
Int
Amount to offset the list of results.
Default is 0.
For example, to get details for a particular user group using the user group's name, you might use the following request:
public/core/v3/userGroups?q=userGroupName=="group_a"
GET response If successful, returns the following information for each user group:
Field
Type
Description
id
String
User group ID.
orgId
String
ID of the organization the user group belongs to.
createdBy
String
User who created the user account.
updatedBy
String
User who last updated the user account.
createTime
String
Date and time the user group was created.
updateTime
String
Date and time the user group was last updated.
userGroupName
String
Name of the user group.
description
String
Description of the user group.
roles
Array
Roles assigned to the user group.
id
String
Included in the roles object.
Role ID.
roleName
String
Included in the roles object.
Role name.
description
String
Included in the roles object.
Description of the role.
displayName
String
Included in the roles object.
Role name that is displayed in the user interface.
displayDescription
String
Included in the roles object.
Role description that is displayed in the user interface.
users
Array
Users assigned to the user group.
id
String
Included in the users object.
User ID.
userName
String
Included in the users object.
User name.
description
String
Included in the users object.
Description of the user.
GET response example If successful, you might receive a response similar to the following example:
[
Creating a user group If you have administrator privileges, you can use the userGroups resource to create a user group.
Note: The number of users, user groups, and roles combined cannot exceed 1000 for an organization.
POST request To create a user group, send a POST request using the following URI:
/public/core/v3/userGroups
Include the following information:
Field
Type
Required
Description
name
String
Yes
Name of the user group.
description
String
-
Description of the user group.
roles
Array
Yes
IDs of the roles to assign to the user group.
users
Array
-
IDs of the users to assign to the user group.
POST response If successful, returns the userGroups object with the details you included in the POST request.
POST example To create a user group, you might send a request similar to the following example:
POST <baseApiUrl>/public/core/v3/userGroups
You might receive a response similar to the following example:
{
Updating a user group You can add users and roles to user groups and remove users and roles from user groups.
Add roles To add a role to a user group, send a PUT request using one of the following URIs:
/public/core/v3/userGroups/<user group ID>/addRoles
/public/core/v3/userGroups/name/<user group name>/addRoles
Include an array of roles to add to the user group.
To add roles to a user group, you might send a request similar to the following example:
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/addRoles
Remove roles To remove a role from a user group, send a PUT request using one of the following URIs:
/public/core/v3/userGroups/<user group ID>/removeRoles
/public/core/v3/userGroups/name/<user group name>/removeRoles
Include an array of roles to remove from the user group.
To remove roles from a user group, you might send a request similar to the following example:
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/removeRoles
Add users To add a user to a user group, send a PUT request using one of the following URIs:
/public/core/v3/userGroups/<user group ID>/addUsers
/public/core/v3/userGroups/name/<user group name>/addUsers
Include an array of user names to add to the user group.
To add users to a user group, you might send a request similar to the following example:
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/addUsers
Remove users To remove a user from a user group, send a PUT request using one of the following URIs:
/public/core/v3/userGroups/<user group ID>/removeUsers
/public/core/v3/userGroups/name/<user group name>/removeUsers
Include an array of user names to remove from the user group.
To remove users from a user group, you might send a request similar to the following example:
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/removeUsers
PUT response Returns a success code if successful or an error object if errors occur.
Deleting a user group You can delete user groups from your organization.
To delete a user group, use the following URI:
/public/core/v3/userGroups/<user group Id>