<access-service>/api/v1/organisations/{orgId}/groups/{groupId}

URL structure

https://access-service.xy-company.com/api/v1/organisations/{orgId}/groups/{groupId}

where {orgId} is the ID of an organization and {groupId} is the ID of one of this organization's groups.

Supported methods and overview

• GET - used to retrieve information about an organization's group, based on the group's ID.
• PUT - used to modify the fields of an organization's group and/or the association of classifications and the membership of Covata users with this group.
• DELETE - used to delete an organization's group.

Note: The GET and DELETE methods take no parameters.

Detailed description

This API endpoint serves a number of purposes:

• Retrieves information about an organization's group, using the group's ID. A group's ID can be obtained by calling the GET method of the <access-service>/api/v1/organisations/{orgId}/groups API endpoint, which retrieves a list of information for all groups in an organization.
  Tip: All information (except the description member) returned in the response from a GET method call to this API endpoint is also returned in the response from a GET method call to the <access-service>/api/v1/organisations/{orgId}/groups endpoint. Therefore, if you do not require a group's description when retrieving information about the group, there is no need to call the GET method on this API endpoint.
• Modifies the fields of an organization's group and/or the association of classifications and the membership of Covata users with this group, based on the group's ID. This endpoint's PUT method allows modification of a group's name and description, as well as:
  • the association (i.e. addition) of classifications with the group,
  • the removal of classifications from the group and
  • the addition (i.e. membership) of Covata users to (or their removal from) this group.
• Deletes a group from an organization.
  Important: Deleting a group removes any association between the Covata users who were members of this group as well as any classifications that were associated with the group. Therefore, if a Covata user was shared a file object with a classification that is associated with one or more groups (of which the user is also a member) and the deletion of one of these groups results in the user:
  • Still remaining associated with this classification (through the classification's association with other groups to which the user is also a member), then the user will still have access to this file object.
  • Losing their association with this classification (because the user was not a member of any other group that had an association with this classification), then the user loses access to this file object.

Supported roles

This API endpoint supports requests utilizing Covata user accounts with the following roles (as described in the Organization Administrator's Guide) and conditions:

• Organization administrator - if this user is a member of the organization specified by the {orgId} of the request's URL.

The Covata Platform's resources available to one of these Covata users (above) is determined by the access token passed in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

The following header is required if the body of the request has a JSON object:

• Content-Type: application/json

Optional parameters

The following optional parameters can also be sent in the body of the PUT request, each as individual members of a JSON object:

• description - .
• labels - .
  • add - .
    • id - .
  • remove - .
    • id - .
• members - .
  • add - .
    • email - .
  • remove - .
    • email - .

• name - .

  Example ():

Returns from a GET or PUT request

A JSON-formatted response containing the following members:

• id - .
• name - .

• description - .

  Example (response from ...):

Returns from a DELETE request

If the request succeeded, then an HTTP response status 200 OK is returned.