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.
To create a new user group, use the POST {baseURL}/v3/usergroups endpoint.
Note
Only Curators can use this API endpoint.
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.
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'
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.
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.
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.
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”.
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.
No parameters required.
curl --location --request GET 'http://localhost/webapi/v3/usergroups' \ --header 'Authorization: Bearer BearerTokenGoesHere'
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.
userGroupId (string): Required. Enter an existing user group ID to retrieve information about this user group.
curl --location --request GET 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069' \ --header 'Authorization: Bearer BearerTokenGoesHere'
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.
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.
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'
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.
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.
curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069/users/61d564361d6d5da7ad461a32' \ --header 'Authorization: Bearer BearerTokenGoesHere'
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.
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.
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.
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.
curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069?forceDelete=true' \ --header 'Authorization: Bearer BearerTokenGoesHere'
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.
POST /v3/usergroups
DELETE /v3/usergroups/{userGroupId}/users/{userId}
To know more about Postman requests, visit the How to Use Postman help page.