User Group Endpoints
User Group Endpoints and Parameters
To learn more about the objects relations and how to use them in the API, go to the Object Relations section.
For more information about Server user groups, visit the User and Group Management help page.
Create a New User Group
To create a new user group, use the POST {baseURL}/v3/usergroups endpoint.
Note
Only Curators can use this API endpoint.
Parameters
To create a new Server user group, specify the contract parameter:
contract (body): Required. Specify the parameters for a Server user group:
name (string): Required. Enter a Server user group name.
role (string): Required. Enter a role for this Server user group. Select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. The default (Evaluated) role is evaluated at runtime. For more information about roles and permissions, visit the User Roles and Permissions page.
Request Example: cURL
curl --location --request POST 'http://localhost/webapi/v3/usergroups' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'name=Accounting' \ --data-urlencode 'role=Artisan'
Add Users to a User Group
To add 1 or more existing users to an existing user group, use the POST {baseURL}/v3/usergroups/{userGroupId}/users endpoint.
Note
Only Curators can use this API endpoint.
Parameters
To add users to a Server user group, specify the following parameters:
userGroupId (string): Required. Enter the ID of the user group to which you want to add users.
userIds (body): Required. Enter the list of user IDs you want to add to this user group, separated by commas.
Add an Active Directory Group to a User Group
To add an Active Directory group to an existing user group, use the POST /v3/usergroups/{userGroupId}/activedirectorygroups endpoint.
Note
Only Curators can use this API endpoint.
This endpoint can only be used for Windows Authentication configured Server instances.
Parameters
userGroupId (string): Required. Enter the ID of an existing user group to which you want to add an Active Directory group.
sid (string): Required. Enter the security identifier (SID) of the Active Directory group. This is a JSON body payload. You must submit the value in quotation marks, for example “S-My-SID”.
Retrieve All User Groups
To retrieve all accessible user group records, use the GET {baseURL}/v3/usergroups endpoint. Use various parameters as a filter for searching the users.
Note
Only Curators can use this API endpoint.
Only Custom User Groups will be retrieved. No Active Directory Groups will be returned.
Parameters
No parameters required.
Request Example: cURL
curl --location --request GET 'http://localhost/webapi/v3/usergroups' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Retrieve Details for a Specific User Group
To retrieve details about an existing user group, use the GET {baseURL}/v3/usergroups/{userGroupId} endpoint.
Note
Only Curators can use this API endpoint.
Only works for Server user groups. Active Directory Groups cannot be retrieved from this endpoint.
Parameters
userGroupId (string): Required. Enter an existing user group ID to retrieve information about this user group.
Request Example: cURL
curl --location --request GET 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Update a User Group
To update an existing user group’s name and role, use the PUT {baseURL}/v3/usergroups/{userGroupId} endpoint.
Note
Only Curators can use this API endpoint.
Parameters
userGroupId (string): Required. Enter a user group ID to get this user group updated.
contract (body): Required. To update a user group, the contract parameter is required. Specify the following:
name (string): Required. Enter a user group name.
role (string): Required. You can select from these options: NoAccess, Viewer, Member, Artisan, Curator, and Evaluated. For more information about roles and permissions, visit the User Roles and Permissions page.
Request Example: cURL
curl --location --request PUT 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --data-urlencode 'name=Marketing' \ --data-urlencode 'role=Artisan'
Remove a User from a User Group
To remove a specific user from an existing user group, use the DELETE {baseURL}/v3/usergroups/{userGroupId}/users/{userId} endpoint.
Note
Only Curators can use this API endpoint.
If the user is not a part of the user group, then an OK response will be returned.
Parameters
userGroupId (string): Required. Enter the ID of the user group from which you want to remove the user.
userId (string): Required. Enter the user ID you want to remove from the user group.
Request Example: cURL
curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069/users/61d564361d6d5da7ad461a32' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Remove an Active Directory Group from a User Group
To remove an Active Directory group from an existing user group, use the DELETE /v3/usergroups/{userGroupId}/activedirectorygroups/{adGroupSid} endpoint.
Note
Only Curators can use this API endpoint.
This endpoint can only be used for Windows Authentication configured Server instances.
Parameters
userGroupId (string): Required. Enter the identifier of the user group from which you want to remove the Active Directory group.
adGroupSid (string): Required. Enter the security identifier (SID) of the Active Directory group you want to remove from the user group.
Delete a User Group
To delete an existing user group from the system, use the DELETE {baseURL}/v3/usergroups/{userGroupId} endpoint.
Note
Only Curators can use this API endpoint.
The ‘400 Bad Request’ error message is returned if the user group is not empty and the forceDelete query parameter is false.
Parameters
userGroupId (string): Required. Enter the user group ID you want to delete.
forceDelete (boolean): Optional. If set to true, the user group will be deleted even if this user group contains users.
Request Example: cURL
curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069?forceDelete=true' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Objects Relations
If you are creating a user group, you can use created objects as follows:
Object created: "id" (for example, "id": "619158e57e607d0011ac3009")
You can use it as:
userGroupId if you are adding a user group to a collection.
userGroupId if you are updating user group permissions of a collection.
userGroupId if you are removing a user group from a collection.
userGroupId if you want to share a credential with a user group.
userGroupId if you want to remove a user group from a credential.
userGroupId if you want to add a user group to a data connection.
userGroupId if you want to remove a user group from a data connection.
Postman Request Examples
POST /v3/usergroups
DELETE /v3/usergroups/{userGroupId}/users/{userId}
To know more about Postman requests, visit the How to Use Postman help page.