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

​

URL structure

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

​

Supported methods and overview

• GET - retrieves information about a group (specified by groupId) defined in an organization (specified by orgId).
• PUT - modifies the fields of an existing group (specified by groupId) in an organization (specified by orgId), which includes the association of classifications and the membership of Covata users in the organization with this group.
• DELETE - deletes an existing group (specified by groupId) in an organization (specified by orgId).

​

Detailed description

• Retrieves information about a group (specified by groupId) defined in an organization (specified by orgId). 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 defined in an organization (specified by orgId).
  Tip: All information returned in the response from a GET request to this API endpoint is also returned in the response from the <access-service>/api/v1/organisations/{orgId}/groups endpoint. Therefore, there is no need to call the GET method on this endpoint if you already have a group’s name, description and/or id from calling <access-service>/api/v1/organisations/{orgId}/groups.
• Modifies the fields of an existing group (specified by groupId) in an organization (specified by orgId), which includes the association of classifications and the membership of Covata users with this group. This endpoint’s PUT method allows modification of the group’s name and description, as well as:
  • the association (i.e. addition or removal) of classifications (configured through the <access-service>/api/v1/organisations/{orgId}/labels) and related API endpoints) with the group and
  • the addition (i.e. membership) of Covata users to (or their removal from) the group.
• Deletes an existing group (specified by groupId) from an organization (specified by orgId).
  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 is not a member of any other group that remains associated with this classification), then the user loses access to this file object.

​

Supported roles and conditions

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

​

Required headers

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

• Content-Type: application/json

​

Optional parameters

• name - The updated name for the group.
• description - The updated description for the group.
• labels - A parameter containing the following optional sub-element parameters that relate to the classifications being added to or removed from this group.
  • add - An array of elements about each classification to be added to this group.
    • id - The ID of a classification to be added to this group. This classification must be configured within the organization specified by {orgId} in the request’s URL.
  • remove - An array of elements about each classification to be removed from this group.
    • id - The ID of a classification to be removed from this group.
• members - A parameter containing the following optional sub-element parameters that relate to the Covata user accounts being added to or removed from this group.
  • add - An array of elements about each user account to be added to this group.
    • email - The email address of a Covata user account to be added to this group. This Covata user must also be a member of the organization specified by {orgId} in the request’s URL.
  • remove - An array of elements about each user account to be removed from this group.
    • email - The email address of a Covata user account to be removed from this group.
  Example (request):
  {
    "name": "Company partners (without any security clearance)",
    "description": "Staff members of companies partnered with XY Company, who themselves do not have any security clearance within their organization.",
    "labels": {
      "add": [
        {
          "id": "766862496543055872"
        }
      ]
    },
    "members": {
      "add": [
        {
          "email": "alex.originator@xy-company.com"
        }
      ]
    }
  }
  

​

Returns

• description - The (updated) description of the group.
• name - The (updated) name of the group.
• id - The ID of the group.
  Example (response from a GET or PUT request):
  {
      "description": {
          "value": "Staff members of companies partnered with XY Company, who themselves do not have any security clearance within their organization."
      },
      "name": {
          "value": "Company partners (without any security clearance)"
      },
      "id": "767257860555186176"
  }