User Group Endpoints
Server 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 Server User Group
To create a new Server user group, use the POST {baseURL}/v3/usergroups 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 a User to a Server User Group
To add one or more users to a Server user group, use the POST {baseURL}/v3/usergroups/{id}/users endpoint.
Parameters
To add users to a Server user group, specify the following parameters:
id (string): Required. Enter the ID of the Server user group to which you want to add users.
userIds (body): Required. Enter the user IDs you want to add to this Server user group.
Add an Active Directory Group as a Member of a Server User Group
To add an Active Directory group as a member of a Server user group, use the POST /v3/usergroups/{id}/activedirectorygroups endpoint.
Note
This endpoint can only be used for Windows Authentication configured Server instances.
Parameters
id (string): Required. Enter the ID of an existing Server 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. You must submit the value in quotation marks, for example “S-My-SID”.
Retrieve All Server User Groups
To search for users, use the GET {baseURL}/v3/usergroups endpoint. Use various parameters as a filter for searching the users.
Note
Only Server 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'
Search for a Specific Server User Group
To retrieve information about a specific Server user group, use the GET {baseURL}/v3/usergroups/{id} endpoint.
Note
Only works for Server user groups. Active Directory Groups cannot be retrieved from this endpoint.
Parameters
id (string): Required. Enter a Server 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 Server User Group
To update an existing Server user group’s name and role, use the PUT {baseURL}/v3/usergroups/{id} endpoint.
Parameters
id (string): Required. Enter a Server user group ID to get this user group updated.
contract (body): Required. To update a Server user group, the contract parameter is required. Specify the following:
name (string): Required. Enter a Server 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 Server User Group
To remove a specific user from a Server user group, use the DELETE {baseURL}/v3/usergroups/{userGroupId}/users/{userId} endpoint.
Note
If the user is not a part of the group, then an OK response will be returned.
Parameters
userGroupId (string): Required. Enter the ID of the Server user group from which you want to remove the user.
userId (string): Required. Enter the user ID you want to remove from the Server 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 Being a Member of a Server User Group
To remove an Active Directory group from being a member of a Server user group, use the DELETE /v3/usergroups/{userGroupId}/activedirectorygroups/{adGroupSid} endpoint.
Note
This endpoint can only be used for Windows Authentication configured Server instances.
Parameters
userGroupId (string): Required. Enter the identifier of the Server user group from which you want to remove the Active Directory group.
adGroupSid (string): Required. Enter the security identifiere (SID) of the Active Directory group you want to remove from the Server user group.
Delete a Server User Group
To delete a specific Server user group from the system, use the DELETE {baseURL}/v3/usergroups/{id} endpoint.
Note
The ‘400 Bad Request’ error message is returned if the Server user group is not empty and the forceDelete query parameter is false.
Parameters
id (string): Required. Enter the Server user group ID you want to delete.
forceDelete (boolean): Optional. If set to true, the Server 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 Server 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 Server user group to a collection.
userGroupId if you are updating Server user group permissions of a collection.
userGroupId if you are removing a Server user group from a collection.
userGroupId if you want to share a credential with a Server user group.
userGroupId if you want to remove a Server user group from a credential.
userGroupId if you want to add a Server user group to a data connection.
userGroupId if you want to remove a Server 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.