The owner of an item (either a Secure Object or collection) can share this item with other people, who could be other Covata users or people who do not yet have a user account on the Covata Platform.

A person who has been shared an item (by its owner) is referred to as a collaborator. If someone does not yet have a Covata user account, the act of sharing an item with this person (via their email address) automatically creates that person a user account on the Covata Platform (with the Ad hoc role).

An item's owner can apply one of up to four sets of permissions (each of which is referred to as a permission set) to a collaborator on the item, such that each collaborator is associated with their own permission set on any given item. A permission set grants the collaborator one or more individual permissions, each of which permit the collaborator to perform various actions on that item and its contents. For more information about permission sets and the individual permissions they grant, see <access-service>/api/v1/permissions/sets.

All collaborators and their permission sets on a collection are implicitly cascaded down through that collection and the items contained within it. This means that if a collection has been shared with a collaborator and a given permission set, then that collaborator can access and perform specific actions (based on the permissions granted by this permission set) on this collection, as well as on every item contained within this collection. If, however, the collection's owner had done one of the following to one of these collaborators on a descendant item within this collection:

removed the collaborator from the descendant item, or
changed the collaborator's permission set on this descendant item,

then this modification is made explicitly on this descendant item, which has the following implications:

Any implicit sharing this collaborator had to this descendant item (inherited implicitly from the closest ancestral collection) is overridden by this explicit modification.
If the descendant item is a collection, then the explicit modification on this descendant collection is implicitly cascaded down through the items contained within.

This page describes how to use Covata's API to:

Notes:

Before sharing a Secure Object or a collection, your application must have a valid access token obtained by authenticating and authorizing a Covata user to the Covata Platform, where this user has the appropriate role and/or permissions to create their own items to share.
For more information about authenticating and authorizing Covata users to the Covata Platform, see Initiating authentication and authorization on the Authentication and authorization page of this guide and the Configuring client applications page of the Safe Share Administrator's Guide.

The Supported roles (and conditions) sections of each API endpoint page (linked to from the procedures below) contain details about the roles and permissions that a Covata user requires for a successful request to the endpoint (along with a valid access token representing this user).

Sharing a Secure Object with collaborators

A Secure Object can be shared with collaborators when the Secure Object is either first created/initialized or completed (if its data is encrypted locally), or at any time thereafter.

To a Secure Object with collaborators, do one of the following ⁽¹⁾:

Make a POST request to the <access-service>/api/v1/organisations/{orgGroupId}/objects API endpoint with a JSON object in the body of the request containing:
- A collaborators parameter pair whose value is an object containing:
  - A list parameter pair whose value is an array containing object elements, each of which represents a collaborator. Each of these objects contains the following members:
    - email - A parameter pair whose value is the email address of the collaborator.
    - permissionSet - A parameter pair whose value is an object containing a single id parameter (as a name/value pair), where the value is the ID of the specific permission set to apply to this collaborator. See <access-service>/api/v1/permissions/sets for more information about retrieving the ID of a permission set.
- The keyId parameter (name/value pair) whose value is the ID of the key (obtained earlier).
- If the Secure Object is to be completed (and its data encrypted locally), then also include the sha512 parameter (name/value pair), whose value is the SHA-512 value of this locally encrypted data.
Make a PUT request to the <access-service>/api/v1/objects/{objectId} API endpoint with a JSON object in the body of the request containing the collaborators (and if required, the sha512) parameter pair/s (above).

⁽¹⁾ For all of these actions, a valid access token representing the Covata user who either will own the Secure Object being created or currently owns the Secure Object in question, must be included in the header of the requests.

Sharing a collection with collaborators

A collection can be shared with collaborators when the collection is either first created or at any time thereafter.

To share a collection with collaborators, do one of the following ⁽²⁾:

Make a POST request to the <access-service>/api/v1/collections API endpoint with a JSON object in the body of the request containing:
- A collaborators parameter pair whose value is an object containing:
  - A list parameter pair whose value is an array containing object elements, each of which represents a collaborator. Each of these objects contains the following members:
    - email - A parameter pair whose value is the email address of the collaborator.
    - permissionSet - A parameter pair whose value is an object containing a single id parameter (as a name/value pair), where the value is the ID of the specific permission set to apply to this collaborator. See <access-service>/api/v1/permissions/sets for more information about retrieving the ID of a permission set.
- The name and parentId parameters (name/value pairs) whose values are described earlier for creating a collection.
Make a PUT request to the <access-service>/api/v1/collections/{collectionId} API endpoint with a JSON object in the body of the request containing the collaborators (and if required, the name and parentId) parameter pair/s (above).

⁽²⁾ For all of these actions, a valid access token representing the Covata user who either will own the collection being created or currently owns the collection in question, must be included in the header of the requests.

Determining existing collaborators on an item

To determine the existing collaborators (and their respective permission sets) on a Secure Object or collection:

Retrieve the ID of this item, which can be achieved by retrieving information about a filtered subset of items from the Covata Platform.
Call the <access-service>/api/v1/items/{itemId} API endpoint, where {itemId} is the ID of the item in question. The JSON response reveals all collaborators on the item, as well as each collaborator's respective permission set (and the individual permissions that constitute the permission set).
Note: For this JSON response to reveal information about collaborators on this item, then the (valid) access token (in the header of the request) must meet the following conditions:
- Relate to a Covata user who either owns this item or is a collaborator on the item.
- If the Covata user is a collaborator on this item, they must have either the Upload or Manage permission set on the item (or more specifically, the individual View Other permission) to retrieve information about other collaborators on the item.
  Be aware that if the item is a Secure Object (on which the Covata user inherited the Upload permission set from a ancestral collection), then the user's permission set on this Secure Object (along with the corresponding individual permissions) are 'demoted' to the Download permission set (and corresponding individual permissions), since some of the Upload permission set's individual permissions do not apply to Secure Objects. Nevertheless, the currently authenticated Covata user can observe all their individual permissions to this Secure Object through the top-level permissions member in the JSON response. For more information about permission sets and their individual permissions, see <access-service>/api/v1/permissions/sets.

Modifying existing collaborators on an item

Collaborators can be modified on a Secure Object or collection by:

removing existing collaborators from the item,
changing the permission set of existing collaborators on the item, or
adding new collaborators to the item (which is already shared with existing collaborators).

To modify existing collaborators, follow the relevant PUT request process above for initially sharing a Secure Object or collection with collaborators. However, when making this PUT request, if you intend to:

Remove existing collaborators from the item, then ensure the collaborators who should not be removed are re-applied in the PUT request (along with their respective permission sets).
Change the permission sets of existing collaborators on the item, ensure existing collaborators are re-applied in the PUT request (along with their respective permission sets). However, for each collaborator whose permission set needs modifying, specify the id parameter of the permissionSet parameter with the updated permission set ID.
Add new collaborators to the item, ensure all existing collaborators and their respective permission sets are re-applied in the PUT request, along with any new collaborators.

Tip: It is worthwhile your client application storing existing collaborators (with whom a Secure Object or collection was last shared, along with the collaborators respective permission sets) in an object. Doing so avoids the need to retrieve an item to determine its existing collaborators and their permission sets).