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

​

URL structure

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

​

Supported methods and overview

• POST - adds a new clearance to an organisation (specified by orgId).
• GET - retrieves a list of information for all clearances defined within an organisation (specified by orgId).

​

Detailed description

• Adds a new clearance to an organisation (specified by orgId).
  Notes:
  • Associating this new clearance with one or more classifications would allow these classifications to restrict file sharing to any Covata users who are members of this clearance.
  • For more information about adding one or more Covata users in an organisation to a clearance, see <access-service>/api/v1/organisations/{orgId}/groups/{groupId}. Also see <access-service>/api/v1/organisations/{orgId}/labels for more information about adding new classifications to an organisation.
• Retrieves a list of information for all clearances defined within an organisation (specified by orgId).

​

Supported roles and conditions

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

​

Required headers

• Authorisation: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

• Content-Type: application/json

​

Required POST-request parameters

• name - The name of the new clearance to be added to the organisation specified by {orgId} in the request’s URL.
  Example (request):
  {
    "name": "Staff with security clearance"
  }
  

​

Optional POST-request parameters

• description - The description of the new clearance to be added to the organisation specified by {orgId} in the URL.
  Example (request):
  {
    "name": "Staff with security clearance",
    "description": "XY Company staff members who have security clearance."
  }
  

​

Optional GET-request parameters

• limit - An integer value from 0 to 100, representing the maximum number of items to be returned in the response, where an individual item is information about a clearance defined in the organisation (specified by {orgId} in the request’s URL). If this parameter is omitted, then its value is 0 by default, which does not apply restrictions to the number of items returned in the response.
• offset - A value representing the count order of all retrievable items (i.e. clearances in the organisation specified by {orgId} in the URL) returned in the response. Calls to this API endpoint may amount to potentially large numbers of items being returned from the Covata Platform. Since the order of these items in the response could differ significantly, based on the values of the orderBy and sortBy parameters below, this offset parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than 0 (i.e. the first item returned in a response). If this parameter is omitted, then its value is 0 by default.
• orderBy - An enumeration (enum) value representing the order in which items (i.e. clearances in the organisation specified by {orgId} in the URL) are returned in the response. This parameter orders items according to the value of the sortBy parameter specified below. Ordering items can be in either ascending alphanumeric order (by specifying the value ASC for this parameter) or descending order (by specifying the value DESC). If this parameter is omitted, then its value is ASC by default.
• sortBy - A value representing the field (i.e. member) of a retrieved item by which items (i.e. clearances in the organisation specified by {orgId} in the URL) returned in the response will be sorted. Valid field values for this parameter include:
  • name - the name of the clearance and
  • description - the description of the clearance.
  Example (request):
  https://access-service.xy-company.com/api/v1/organisations/760756644367081472/groups?sortBy=name
  

​

Returns

• items ( from GET requests only ) - An array containing information about all existing clearances defined in the organisation (specified by {orgId} in the request’s URL), where these clearances have been filtered by any parameters submitted in the request. Each element of this array contains information about one of these clearances (represented as an object containing the following members unless otherwise stated).
• id - The ID of the (new) clearance.
• labelCount ( from GET requests only ) - The number of classifications which are currently associated with the clearance.
• memberCount ( from GET requests only ) - The number of Covata user accounts which are currently members of the clearance.
• description - The description of the (new) clearance.
• name - The name of the (new) clearance.
• count ( from GET requests only ) - The total number of items (i.e. clearances defined in the organisation specified by {orgId} in the request’s URL) that can be returned in the response.
• offset ( from GET requests only ) - The value of the offset which had been used in the request to this API endpoint.
  Example (response from a POST request - adding a new clearance to an organisation):
  {
      "description": {
          "value": "XY Company staff members who have security clearance."
      },
      "name": {
          "value": "Staff with security clearance"
      },
      "id": "767238352499154944"
  }
  
  
  Example (response from a GET request):
  {
      "items": [{
          "id": "766891761892368384",
          "labelCount": "2",
          "memberCount": "3",
          "description": {
              "value": "XY Company staff members who do not have security clearance."
          },
          "name": {
              "value": "Staff"
          }
      }, {
          "id": "767238352499154944",
          "labelCount": "0",
          "memberCount": "0",
          "description": {
              "value": "XY Company staff members who have security clearance."
          },
          "name": {
              "value": "Staff with security clearance"
          }
      }],
      "count": "2",
      "offset": "0"
  }