[en] User Group Endpoints
[en] Server User Group Endpoints and Parameters
[en] To learn more about the objects relations and how to use them in the API, go to the Object Relations section.
[en] For more information about Server user groups, visit the User and Group Management help page.
[en] Create a New Server User Group
[en] To create a new Server user group, use the POST {baseURL}/v3/usergroups endpoint.
[en] Parameters
[en] To create a new Server user group, specify the contract parameter:
[en] contract (body): Required. Specify the parameters for a Server user group:
[en] name (string): Required. Enter a Server user group name.
[en] 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.
[en] Request Example: cURL
[en] 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'
[en] Add a User to a Server User Group
[en] To add one or more users to a Server user group, use the POST {baseURL}/v3/usergroups/{id}/users endpoint.
[en] Parameters
[en] To add users to a Server user group, specify the following parameters:
[en] id (string): Required. Enter the ID of the Server user group to which you want to add users.
[en] userIds (body): Required. Enter the user IDs you want to add to this Server user group.
[en] Add an Active Directory Group as a Member of a Server User Group
[en] To add an Active Directory group as a member of a Server user group, use the POST /v3/usergroups/{id}/activedirectorygroups endpoint.
注意
[en] This endpoint can only be used for Windows Authentication configured Server instances.
[en] Parameters
[en] id (string): Required. Enter the ID of an existing Server user group to which you want to add an Active Directory group.
[en] 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”.
[en] Retrieve All Server User Groups
[en] To search for users, use the GET {baseURL}/v3/usergroups endpoint. Use various parameters as a filter for searching the users.
注意
[en] Only Server user groups will be retrieved. No Active Directory Groups will be returned.
[en] Parameters
[en] No parameters required.
[en] Request Example: cURL
[en] curl --location --request GET 'http://localhost/webapi/v3/usergroups' \ --header 'Authorization: Bearer BearerTokenGoesHere'
[en] Search for a Specific Server User Group
[en] To retrieve information about a specific Server user group, use the GET {baseURL}/v3/usergroups/{id} endpoint.
注意
[en] Only works for Server user groups. Active Directory Groups cannot be retrieved from this endpoint.
[en] Parameters
[en] id (string): Required. Enter a Server user group ID to retrieve information about this user group.
[en] Request Example: cURL
[en] curl --location --request GET 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069' \ --header 'Authorization: Bearer BearerTokenGoesHere'
[en] Update a Server User Group
[en] To update an existing Server user group’s name and role, use the PUT {baseURL}/v3/usergroups/{id} endpoint.
[en] Parameters
[en] id (string): Required. Enter a Server user group ID to get this user group updated.
[en] contract (body): Required. To update a Server user group, the contract parameter is required. Specify the following:
[en] name (string): Required. Enter a Server user group name.
[en] 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.
[en] Request Example: cURL
[en] 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'
[en] Remove a User from a Server User Group
[en] To remove a specific user from a Server user group, use the DELETE {baseURL}/v3/usergroups/{userGroupId}/users/{userId} endpoint.
注意
[en] If the user is not a part of the group, then an OK response will be returned.
[en] Parameters
[en] userGroupId (string): Required. Enter the ID of the Server user group from which you want to remove the user.
[en] userId (string): Required. Enter the user ID you want to remove from the Server user group.
[en] Request Example: cURL
[en] curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069/users/61d564361d6d5da7ad461a32' \ --header 'Authorization: Bearer BearerTokenGoesHere'
[en] Remove an Active Directory Group from Being a Member of a Server User Group
[en] To remove an Active Directory group from being a member of a Server user group, use the DELETE /v3/usergroups/{userGroupId}/activedirectorygroups/{adGroupSid} endpoint.
注意
[en] This endpoint can only be used for Windows Authentication configured Server instances.
[en] Parameters
[en] userGroupId (string): Required. Enter the identifier of the Server user group from which you want to remove the Active Directory group.
[en] adGroupSid (string): Required. Enter the security identifiere (SID) of the Active Directory group you want to remove from the Server user group.
[en] Delete a Server User Group
[en] To delete a specific Server user group from the system, use the DELETE {baseURL}/v3/usergroups/{id} endpoint.
注意
[en] The ‘400 Bad Request’ error message is returned if the Server user group is not empty and the forceDelete query parameter is false.
[en] Parameters
[en] id (string): Required. Enter the Server user group ID you want to delete.
[en] forceDelete (boolean): Optional. If set to true, the Server user group will be deleted even if this user group contains users.
[en] Request Example: cURL
[en] curl --location --request DELETE 'http://localhost/webapi/v3/usergroups/61d58ac83c15317e1a482069?forceDelete=true' \ --header 'Authorization: Bearer BearerTokenGoesHere'
[en] Objects Relations
[en] If you are creating a Server user group, you can use created objects as follows:
[en] Object created: "id" (for example, "id": "619158e57e607d0011ac3009")
[en] You can use it as:
[en] userGroupId if you are adding a Server user group to a collection.
[en] userGroupId if you are updating Server user group permissions of a collection.
[en] userGroupId if you are removing a Server user group from a collection.
[en] userGroupId if you want to share a credential with a Server user group.
[en] userGroupId if you want to remove a Server user group from a credential.
[en] userGroupId if you want to add a Server user group to a data connection.
[en] userGroupId if you want to remove a Server user group from a data connection.
[en] Postman Request Examples
[en] POST /v3/usergroups
[en] DELETE /v3/usergroups/{userGroupId}/users/{userId}
[en] To know more about Postman requests, visit the How to Use Postman help page.