<access-service>/api/v1/collections/{collectionId}

URL structure

https://access-service.xy-company.com/api/v1/collections/{collectionId}

where {collectionId} is the ID of a collection.

Supported methods and overview

• GET - used to retrieve information about a collection, based on the collection's ID.
• PUT - used to modify a collection's attributes/metadata, which involves the owner¹ of this collection performing any combination of the following:
  • Modifying the collaborators (as well as their permission sets) on a collection.
  • Moving and renaming the collection.
    Note: A collaborator on the collection (with the Manage permission set) can also perform these actions.
• DELETE - used to delete a collection. Unlike deleting Secure Objects, deleting a collection removes all trace of the collection and its attributes/metadata from the Covata Platform.

Note: Both the GET and DELETE methods take no parameters.

¹ A collection's owner is the Covata user whose account was used to create the collection. (A collection's ownership can also be changed to that of another Covata user.)

Detailed description

This API endpoint serves a number of purposes:

• Retrieves information about a collection, using the collection's ID. A collection's ID can be obtained by calling the <access-service>/api/v1/items API endpoint, which retrieves a list of information associated with collections that can be filtered using various 'search' criteria.
• Allows the collection's owner² to modify the collection's attributes/metadata, which include the following:
  • Parent collection (specified through this endpoint's parentId parameter) - the collection to which this collection (whose ID is specified in the {collectionId} part of this request's URL) will be moved.
  • Name (specified through this endpoint's name parameter) - the name of this collection.
  • Collaborators and their permission sets (specified through this endpoint's collaborators parameter) - where a permission set is specific to each individual collaborator. For each collaborator, one of the following four permission sets can be applied:
    • Download - grants the collaborator the following permissions on any Secure Objects³ contained within this collection:
      • Download the Secure Object's content (by calling the GET method on the <content-service>/api/v1/objects/{objectId}/contents endpoint).
      • Print and View the Secure Object's content from a Safe Share application's content viewer. The View permission also allows the Secure Object's read-only view to be downloaded (by calling the GET method on the <content-service>/api/v1/objects/{objectId}/view endpoint).
    • Manage - grants the collaborator the following permissions to perform any of the following actions on any Secure Objects³ contained within this collection and/or the content of these Secure Objects in the owner's storage space:
      • Download the Secure Object's content.
      • Delete the Secure Object and its content (by calling the DELETE method on the <content-service>/api/v1/objects/{objectId}/contents endpoint followed by the DELETE method on the <access-service>/api/v1/objects/{objectId} endpoint), through the Remove (File) permission.
      • Move the Secure Object to a different collection within a common collection hierarchy (by calling the PUT method on the <access-service>/api/v1/objects/{objectId} endpoint). A common collection hierarchy is a collection hierarchy that contains either this new collection or the Secure Object (subsequently contained within this new collection), where the owner of this item has also added the same collaborator (with the Manage permission set) to the collection hierarchy's parent (i.e. the root-level) collection.
      • Print the Secure Object's content from the Safe Share web application's content viewer.
      • Rename the Secure Object (by calling the PUT method on the <access-service>/api/v1/objects/{objectId} endpoint).
      • View the Secure Object's content in a Safe Share application's content viewer, which also allows the Secure Object's read-only view to be downloaded.
      The Manage permission set also grants the collaborator the ability to perform the following within this collection (as the parent collection):
      • Initialize a new Incomplete Secure Object or create a new completed Secure Object (whose state is Created) within this parent collection, through the Upload File permission. This is achieved by calling the POST method on the <access-service>/api/v1/organisations/{orgGroupId}/objects endpoint with the parentId parameter value being that of this parent collection and either with or without the Secure Object's SHA512 value.
      • Create a new child collection within this parent collection, through the Create Folder permission. This is achieved by calling the <access-service>/api/v1/collections endpoint with the parentId parameter value being that of this parent collection.
      • Delete a child collection and its content within this parent collection, through the Remove (Folder) permission. This is achieved by calling the DELETE method on this endpoint with the parentId parameter value being that of this parent collection and the child collection specified in the {collectionId} part of the request's URL.
        Important: Be aware that a more restrictive permission set applied to any items contained within this child collection being deleted are ignored and as such, these items will also be deleted.
    • Upload - grants the collaborator the following permissions to perform any of the following actions on any Secure Objects³ contained within this collection and/or the content of these Secure Objects in the owner's storage space:
      • Download the Secure Object's content.
      • Print and View the Secure Object's content from a Safe Share application's content viewer, which also allows the Secure Object's read-only view to be downloaded.
      The Upload permission set (which grants the Upload File permission) also grants the collaborator the ability to initialize a new Incomplete Secure Object or create a new completed Secure Object (whose state is Created) within this new collection (as a parent collection), once this collection has been created.
    • View - grants the collaborator the View permission on any Secure Objects³ contained within this collection, which allows these Secure Objects':
      • content to be viewed from a Safe Share application's content viewer, as well as
      • read-only views to be downloaded.
• Deletes a collection. This has the following effects:
  • The collection (including any other collections contained within it) are deleted from the database of the Covata Platform's Access Service. Hence, the attributes/metadata associated with these collections will no longer be available.
  • The state of all Secure Objects that were contained within the collection are changed to Deleted. The encrypted data associated with these Secure Objects contained in storage (i.e. the encrypted data managed by the Covata Platform's Content Service) is also physically deleted (see Note below). However, the attributes/metadata associated with these Secure Objects are still retained by the Access Service.
  Note: The encrypted data of all Secure Objects contained within the collection (deleted via this endpoint) is also automatically deleted from storage by the Content Service. However, this process only occurs every two hours (by default) or when a new access token (belonging to the owner of this collection and excluding those obtained through a refresh token) is passed in the header of requests to this endpoint. Therefore, it is strongly advised that you first explicitly delete this data in storage before calling this API endpoint with the DELETE method (to change the state of all Secure Objects contained within the collection to Deleted). If not, then the Covata user's actual quota will differ from the quota reported by the Covata Platform (until this data is automatically deleted by the Content Service).

² A collection's owner is the Covata user whose account was used to create the collection. (A collection's ownership can also be changed to that of another Covata user.)

³ If any of these Secure Objects are subsequently contained within a nested (i.e. child) collection to which a more restrictive permission set (listed above) has been applied for a given collaborator, then that collaborator will only possess the relevant permissions (granted by this more restrictive permission set) on this child collection and any other items contained within it. The exceptions are the Remove (File) and Remove (Folder) permissions, which are propagated down through a collection hierarchy, regardless of whether or not a more restrictive permission set has been applied to an item further down the hierarchy.

Supported roles and conditions

This API endpoint supports the following Covata user roles (as described in the Covata Platform Administrator's Guide), conditions and permissions (where applicable):

• Originator - a Covata user with this role can call the GET, PUT and DELETE methods on a collection they own.
• Originator, Collaborator and Ad hoc - a Covata user with any of these roles can call:
  • the GET method for a collection they are a collaborator on (with the View permission)
  • the parentId and name parameters of the PUT method for a collection they are a collaborator on (with the Move and Rename permissions, respectively) and
  • the DELETE method for a collection they are a collaborator on (with the Remove (Folder) permission).

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 a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6

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 be sent in the body of the PUT request, each as individual members of a JSON object:

• collaborators - A parameter containing the following optional sub-element parameters, relating to the collaborators being applied to this collection:
  • list - An array of elements about each collaborator, where each element of this array contains the following optional sub-elements:
    • email - The email address of the person to add as a collaborator to the collection. (Although this sub-element is optional, omitting it serves no purpose.)
    • permissionSet - The permission set to apply to this collaborator. This is done by specifying the ID of the permission set as a sub-element parameter of this parameter:
      • id - The ID of the permission set to apply to this collaborator. This ID can be obtained by calling the <access-service>/api/v1/permissions/sets API endpoint.
      Note: If this sub-element is omitted, then the View permission set is automatically applied to this collaborator.
  • note - A custom message to send as part of an email notification to collaborators (in the list above) once the request is sent.
  Tip: It is worthwhile your client application storing these set of collaborators and their respective permission sets (e.g. in an object) because any modifications to one or more collaborators on an existing collection requires all collaborators and their permission sets to be specified in the collection modification request.
• name - .

• parentId - .

  Example ():

Returns

A JSON-formatted response containing the following members:

• id - .
• name - .
• owner - .
  • email - .
  • firstName - .
  • lastName - .
  • id - .
• modifiedAt - .
• createdAt - .
• originator - .
  • email - .
  • userId - .
• shared - .
• parentId - .
• collaborators - .
  • email - .
  • firstName - .
  • lastName - .
  • id - .

• type - .

  Example (response from ...):