URL structure
1 https://access-service.xy-company.com/api/v1/organisations/{orgId}/groups/{groupId}
where {orgId} is the ID of an organisation and {groupId} is the ID of one of this organisation's clearances.
Supported methods and overview
GET - retrieves information about a clearance (specified by groupId) defined in an organisation (specified by orgId).PUT - modifies the fields of an existing clearance (specified by groupId) in an organisation (specified by orgId), which includes the association of classifications and the membership of Cocoon Data users in the organisation with this clearance.DELETE - deletes an existing clearance (specified by groupId) in an organisation (specified by orgId).
Note: The GET and DELETE methods take no parameters.
Detailed description
This API endpoint serves a number of purposes:
- Retrieves information about a clearance (specified by
groupId) defined in an organisation (specified by orgId). A clearance'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 clearances defined in an organisation (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 clearance's name, description and/or id from calling <access-service>/api/v1/organisations/{orgId}/groups.
- Modifies the fields of an existing clearance (specified by
groupId) in an organisation (specified by orgId), which includes the association of classifications and the membership of Cocoon Data users with this clearance. This endpoint's PUT method allows modification of the clearance's name and description, as well as:
- Deletes an existing clearance (specified by
groupId) from an organisation (specified by orgId).
Important: Deleting a clearance removes any association between the Cocoon Data users who were members of this clearance as well as any classifications that were associated with the clearance. Therefore, if a Cocoon Data user was shared a file object with a classification that is associated with one or more clearances (of which the user is also a member) and the deletion of one of these clearances results in the user:
- Still remaining associated with this classification (through the classification's association with other clearances 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 clearance that remains associated with this classification), then the user loses access to this file object.
Supported roles and conditions
This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:
The Cocoon Data Platform's resources available to one of these Cocoon Data users (above) is determined by the access token submitted 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:
-
name - The updated name for the clearance.
-
description - The updated description for the clearance.
-
labels - A parameter containing the following optional sub-element parameters that relate to the classifications being added to or removed from this clearance.
-
add - An array of elements about each classification to be added to this clearance.
-
id - The ID of a classification to be added to this clearance. This classification must be configured within the organisation specified by
{orgId} in the request's URL.
-
remove - An array of elements about each classification to be removed from this clearance.
-
id - The ID of a classification to be removed from this clearance.
-
members - A parameter containing the following optional sub-element parameters that relate to the Cocoon Data user accounts being added to or removed from this clearance.
-
add - An array of elements about each user account to be added to this clearance.
-
email - The email address of a Cocoon Data user account to be added to this clearance. This Cocoon Data user must also be a member of the organisation specified by
{orgId} in the request's URL.
-
remove - An array of elements about each user account to be removed from this clearance.
-
email - The email address of a Cocoon Data user account to be removed from this clearance.
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 organisation.",
"labels": {
"add": [
{
"id": "766862496543055872"
}
]
},
"members": {
"add": [
{
"email": "alex.originator@xy-company.com"
}
]
}
}
Returns
If the request succeeded, then an HTTP response status 200 OK is returned.
For successful GET and PUT requests only, a JSON-formatted response containing the following members is also returned:
-
description - The (updated) description of the clearance.
-
name - The (updated) name of the clearance.
-
id - The ID of the clearance.
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 organisation."
},
"name": {
"value": "Company partners (without any security clearance)"
},
"id": "767257860555186176"
}
