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

URL structure

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

where {orgId} is the ID of an organisation and {labelId} is the ID of one of this organisation's classifications.

Supported methods and overview

• GET - retrieves information about a classification (specified by labelId) configured in an organisation (specified by orgId).
• DELETE - deletes an existing classification (specified by labelId) in an organisation (specified by orgId).

Note: Both of these methods take no parameters.

Detailed description

This API endpoint serves a number of purposes:

• Retrieves information about a classification (specified by labelId) configured in an organisation (specified by orgId). A classification's ID can be obtained by calling the GET method of the <access-service>/api/v1/organisations/{orgId}/labels API endpoint, which retrieves a list of information for all classifications configured in an organisation (specified by orgId).
  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}/labels endpoint. Therefore, if you do not require a classification's description when retrieving information about the classification, there is no need to call the GET method on this API endpoint.
• Deletes an existing classification (specified by labelId) from an organisation (specified by orgId).
  Important: Deleting a classification also removes:
  • this classification from all new and existing file objects it had been applied to and more importantly,
  • removes all current collaborators from these file objects.

Note: Be aware that by design and for security reasons, it is not possible to edit any aspect of a classification.

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:

• Organisation administrator, Originator, Collaborator, Ad hoc - using the GET method, when this user is a member of the organisation specified by the {orgId} of the request's URL.
• Organisation administrator - using the DELETE method, when this user is a member of the organisation specified by the {orgId} of the request's URL.

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...

Returns

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

For successful GET requests only, a JSON-formatted response containing the following members is also returned:

• id - The ID of the classification.
• name - The name of the classification.
• description - The description of the classification.
• priority - The current priority value, which is used for sorting classifications from highest (i.e. a priority integer value of 1) through to the lowest priority (i.e. the highest priority integer value, which equals the total number of all classifications defined in an organisation).
• applyI18n - .
  Example (response):

  {
      "id": "766855749304623104",
      "name": {
          "value": "Confidential"
      },
      "description": {
          "value": "This classification level is used for content that should only be accessible to members of staff with security clearance. Anyone outside the company (including partners) should not access this content."
      },
      "priority": "1",
      "applyI18n": false
  }