API Documentation
<access-service>/api/v1/objects/{objectId}

URL structure

https://access-service.xy-company.com/api/v1/objects/{objectId}

where {objectId} is the ID of a Secure Object.

Supported methods and overview

  • GET - used to retrieve information about a Secure Object, based on the Secure Object's ID.
  • PUT - used to modify a Secure Object's attributes/metadata, which involves the owner1 of this Secure Object performing any combination of the following:
    • Modifying the collaborators (as well as their permission sets) on a Secure Object.
    • Modifying the label and time/date controls on a Secure Object.
    • Moving and renaming the Secure Object.
      Note: A collaborator on the Secure Object (with the Manage permission set) can also perform these actions.
    • Completing an Incomplete Secure Object (which changes its state to Created).
  • DELETE - used to change a Secure Object's state on the Covata Platform's Access Service to Deleted.

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

1 A Secure Object's owner is the Covata user whose account was used to initialize/create the Secure Object. (A Secure Object'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 Secure Object, using the Secure Object's ID. A Secure Object's ID can be obtained by calling the <access-service>/api/v1/items API endpoint, which retrieves a list of information associated with Secure Objects that can be filtered using various 'search' criteria.
  • Allows a Secure Object's owner2 to modify the Secure Object's attributes/metadata, which include the following:
    • Label (specified through this endpoint's labelId parameter) - defines which groups of Covata users can be shared the Secure Object.
    • Time/date controls (specified through this endpoint's shareStartTime and shareEndTime parameters) - the time and date from which collaborators can begin accessing the Secure Object's content and/or when this access ceases.
    • Parent collection (specified through this endpoint's parentId parameter) - the collection to which the Secure Object will be moved.
    • Name (specified through this endpoint's name parameter) - the name of the Secure Object.
    • 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 three permission sets can be applied:
      • Download - grants the collaborator the following permissions:
      • Manage - grants the collaborator the following permissions to perform any of the following actions on the Secure Object and/or its content 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 this endpoint), through the Remove (File) permission. See Notes below for important information about deleting Secure Objects.
        • Move the Secure Object to a different collection within a common collection hierarchy (by calling the PUT method on this endpoint). A common collection hierarchy is a collection hierarchy that contains this Secure Object/item, where the owner of this item has also added the same collaborator (with the Manage permission set) to the root (or common) collection of this collection hierarchy.
        • 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 this 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.
      • View - grants the collaborator the View permission to allow the Secure Object's:
        • content to be viewed from a Safe Share application's content viewer, as well as
        • read-only view to be downloaded.
  • Allows a Secure Object's owner2 to complete an Incomplete Secure Object (which changes its state to Created), by associating the SHA512 value of data encrypted locally by your client application with the Secure Object. See <access-service>/api/v1/objects for more information about initializing Incomplete Secure Objects.
  • Changes a Secure Object's state (on the Covata Platform's Access Service) to Deleted.
    Notes:
    • The encrypted data associated with this Secure Object (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 Secure Object and excluding access tokens obtained through a refresh token) is passed in the header of requests to this endpoint. Therefore, it is advised that you first explicitly delete this data in storage before calling the DELETE method of this API endpoint (to change the state of this Secure Object to Deleted). If not, then the Covata user's actual quota may differ (potentially significantly) from the quota reported by the Covata Platform (until this data is automatically deleted by the Content Service).
    • Changing a Secure Object's state to Deleted (by calling this endpoint) does not delete the Secure Object's associated attributes/metadata.
    • Be aware that a Secure Object and its associated attributes/metadata are deleted when the Covata user (who owns this Secure Object) is deleted themselves.

2 A Secure Object's owner is the Covata user whose account was used to initialize/create the Secure Object. (A Secure Object's ownership can also be changed to that of another Covata user.)

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 Secure Object they own.
  • Originator, Collaborator and Ad hoc - a Covata user with any of these roles can call:
    • the GET method for a Secure Object they are a collaborator on (with the View permission),
    • the parentId and name parameters of the PUT method for a Secure Object they are a collaborator on (with the Move and Rename permissions, respectively) and
    • the DELETE method for a Secure Object they are a collaborator on (with the Remove (File) 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 Secure Object:
    • 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 Secure Object. (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: 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 Secure Object (through this parameter) overwrites any collaborators (and their permission sets) which had previously been applied to this Secure Object.
  • contentSize - The size (in bytes) of the Secure Object's data (in its unencrypted form) to be recorded by the Covata Platform's Access Service. Specify this value to record the size of a completed Secure Object's unencrypted data, which is to be encrypted locally by your client application.
    Important:
    • The contentSize value can only be set once on a Secure Object.
    • If you intend to upload the Secure Object's unencrypted data to storage via the Covata Platform's Content Service, then omit this parameter. When you make the upload request, the Content Service automatically calculates the size of the unencrypted data and assigns this value to contentSize, before the Content Service proceeds to encrypt the data and send this encrypted data to storage.
    • If you have already specified the contentSize parameter's value before uploading a Secure Object's unencrypted data, then your Secure Object is stuck with this contentSize value as the Content Service cannot assign the unencrypted data's size to contentSize once its value has been set. The Covata Platform's Access and Content Services will record errors in their respective logs. Nevertheless, this unencrypted data will still be successfully encrypted by the Content Service, the encrypted data sent to storage and the encrypted data associated with the Secure Object.
  • labelId - The ID of the label to apply to (or change on) the Secure Object. If this parameter's value is 0 or this parameter is never specified on this Secure Object, then No Label is applied to the Secure Object and no label restrictions (i.e. checks on Covata users' group membership and the association of these groups with labels) are placed on any collaborators applied to this Secure Object.
    Notes:
    • Applying a label has the potential to restrict access to the Secure Object by any inherited collaborators. Inherited collaborators are collaborators who have been able to access this Secure Object because they were explicitly applied to an ancestral collection.
    • If Covata users' group memberships (associated with the label applied to the Secure Object in the request) do not comply with any new or existing collaborators applied to this Secure Object, then this request will fail.
  • mimeType - The MIME type of the data associated with the Secure Object. For example, if the data to be encrypted into this Secure Object is an image in JPEG format, its MIME type value would be image/jpeg.
  • name - The name to apply to (or change on) the Secure Object. For example, this might be the name of the original file (whose data is being encrypted into this Secure Object) and its extension.
  • parentId - The ID of the collection that will contain the Secure object. Use this parameter to move a Secure Object to another collection. For example, specifying a value of 0 results in the Secure Object being moved to the default logical root storage location (if the Secure Object is not already located there).
    Note: Omitting this property (or not chaging its value) results in the Secure Object not being moved.
  • sha512 - The SHA512 value of the Secure Object's encrypted data.
    Important:
    • The sha512 value can only be set once on a Secure Object.
    • Omitting this parameter when updating an Incomplete Secure Object, leaves this Secure Object in an Incomplete state.
    • Specifying this parameter and its value on an Incomplete Secure Object changes the Secure Object's state to Created.
    • Specify this parameter if you have encrypted the Secure Object's data externally (e.g. locally by your client application) and intend to upload this encrypted data to storage via the Covata Platform's Content Service.
    • If you have already specified this parameter's value when you created a new completed Secure Object (whose state is Created), then re-specifying this parameter (with any value) in this PUT request will cause this request to fail.
  • shareStartTime - The date and time from which collaborators can begin accessing the Secure Object's content. Omitting this member makes the Secure Object's content available immediately.
    Note: This parameter should only be specified in conjunction with the collaborators parameter. If the shareStartTime parameter is specified without the collaborators parameter, then the shareStartTime parameter's value will not be saved when the request is submitted.

  • shareEndTime - The date and time from which collaborators' access to the Secure Object's content ceases. Omitting this member makes the Secure Object's content available indefinitely (after its shareStartTime).
    Note: This parameter should only be specified in conjunction with the collaborators parameter. If the shareEndTime parameter is specified without the collaborators parameter, then the shareEndTime parameter's value will not be saved when the request is submitted.

    Example (modifying and completing an Incomplete Secure Object):

    {
    "collaborators": {
    "list": [
    {
    "email": "olly.originator@xy-company.com",
    "permissionSet": {
    "id": 3
    }
    },
    {
    "email": "adhoc.user@another-xy-company.com"
    }
    ],
    "note": "I'm adding you as a collaborator to this file."
    }
    "contentSize": "549732",
    "labelId": "0",
    "mimeType": "image/jpeg",
    "name": "paraglider.jpg",
    "sha512": "3SYaa2M1EUQGEFjVkQAsoX\/htQ8I4eVMQFfeqpNM9lj0ZoeKxThbTgE6YUgTDXINbU36HINYHwQhXKrLV2ldUQ==",
    "shareStartTime": "2014-10-08T05:15:00.000Z",
    "shareEndTime": "2014-10-08T05:30:00.000Z"
    }

    Notes:

    • The permission set with an ID of 3 is Manage. See <access-service>/api/v1/permissions/sets for more information about permission sets.
    • If this Secure Object had existing collaborators and permission sets, then these would be overriden in this example request. For instance, if a Secure Object was created with the collaborators and their permission sets applied in the [example request]

Returns

A JSON-formatted response containing the following members:

  • id - The ID value of the Secure Object.
  • name - The name of the Secure Object, which was set when the Secure Object was initialized or created, or last updated. This value is null if the name was never specified.
  • sha512 - The unique SHA-512 hash value of the encrypted data associated with the created/complete Secure Object. For initialized/Incomplete Secure Objects, this value is null.
  • owner - A member containing information about the Covata user who is the current owner of the Secure Object. This member contains the following sub-members:
    • email - This Covata user's email address (which forms part of the Covata user's user credentials and is utilized to sign in).
    • firstName - The Covata user's first name. This is the first name that appears on the User page of Covata Administration and the My Account feature of the Covata Safe Share web application.
    • lastName - The Covata user's last name. Like the first name (above), this appears on the User page of Covata Administration and the My Account feature of the Safe Share web application.
    • id - The Covata user's ID.
    Note: If the ownership of the Secure Object has never been changed, then this Covata user will be the same as that for the originator (below).
  • hasView - A boolean value that indicates whether or not the Covata Platform's Content Service has generated a read-only view of the Secure Object's data in storage.
    Notes:
    • The Content Service automatically sets this value to true after it sets the value of canGenerateView (below) to true and the Content Service has successfully generated and stored a read-only view of the Secure Object's data.
    • If your client application is managing its own Secure Object data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose.
  • canGenerateView - A boolean value that indicates whether or not the Covata Platform's Content Service is capable of generating a read-only view of the Secure Object's data, based on the file name extension of the original file that was encrypted (as specified in name). Covata determines a file's format (for the purpose of genereating a read-only view) based on this file name externsion. For more information, see File formats supported by the content viewer in the Safe Share User's Guide (for the web application).
    Notes:
    • Assuming the file name extension is one that supports a view being generated, the Content Service then automatically sets this value to true after the Secure Object's data has been successfully uploaded + stored and the size of this data is less than the maximum configured file size for generating a view (i.e. 20 MB by default).
    • If your client application is managing its own Secure Object data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose.
  • mimeType - The MIME type of the data associated with the Secure Object, which was set when the Secure Object was initialized or created, or last updated. This value is null if the mimeType was never specified.
  • originator - A member containing information about the Covata user who created this Secure Object. This member contains the equivalent email and id sub-members only of the owner member (above).
  • labelName - The name of the label applied to this Secure Object. If this element's value is No Label, then a labelID value of 0 was specified (or the labelID parameter was never specified) when the Secure Object was initialized or created, or last updated. This means that no label restrictions (i.e. checks on Covata users' group membership and the association of these groups with labels) have been placed on collaborators added to this Secure Object.
  • shared - A boolean value that indicates whether or not the Secure Object has been shared with any collaborators.
  • contentSize - The amount of space (in bytes) of the Secure Object's data (as recorded by the Covata Platform's Access Service). For initialized/Incomplete Secure Objects, this value should be null.
  • parentId - The ID of the collection that contains the Secure object. A value of 0 indicates that this Secure Object is located at the default logical root storage location.
  • createdAt - The date and time when the Secure Object was either initialized or completed.
  • modifiedAt - The date and time when the Secure Object was last modified. If the Secure Object has only been initialized or completed (see <access-service>/api/v1/objects for more information) without subsequent modification, then this date and time should be close to that of createdAt above.
  • type - Indicates object, which indicates that this response to a request on an item was performed on a Secure Object.
  • labelId - The ID of the label applied to this Secure Object. Like labelName (above), if this element's value is 0, then a labelID value of 0 was specified (or the labelID parameter was never specified) when the Secure Object was initialized or created, or last updated. This means that no label restrictions (i.e. checks on Covata users' group membership and the association of these groups with labels) have been placed on collaborators added to this Secure Object.
  • collaborators - An array containing information about each Covata user who is currently a collaborator on the Secure Object. Each element of this array contains information about one of these Covata users and is represented as an object, containing the following members:
    • shareStartTime - The date and time from which this Covata user can begin accessing the Secure Object's content.
    • shareEndTime - The date and time from which this Covata user's access to the Secure Object's content ceases.
    • shareParentId - Indicates either a value of null or 0. A value of null indicates that the Secure Object's location in its hierarchy of collections (e.g. as indicated in a Safe Share application's list of items) are equivalent between this Covata user and the current owner of this Secure Object. A value of 0 indicates that this Secure Object is being shared at the logical root storage location for this Covata user. In Safe Share applications, this occurs when the owner of the Secure Object has shared this Secure Object with this Covata user, but the Secure Object's parent collection/folder has not also been shared with that Covata user.
    • shareName - Reserved for future use.
    • email - This Covata user's email address (which forms part of the Covata user's user credentials and is utilized to sign in).
    • firstName - The Covata user's first name. This is the first name that appears on the User page of Covata Administration and the My Account feature of the Covata Safe Share web application.
    • lastName - The Covata user's last name. Like the first name (above), this appears on the User page of Covata Administration and the My Account feature of the Safe Share web application.
    • id - The Covata user's ID.

  • state - Indicates the current state of the Secure Object, which could be Incomplete for an initialized Secure Object, Created for a completed Secure Object or Deleted for a deleted Secure Object.

    Example (response from modifying and completing an Incomplete Secure Object):

    {
    "id": "987654321098765432",
    "name": "paraglider.jpg",
    "sha512": "3SYaa2M1EUQGEFjVkQAsoX\/htQ8I4eVMQFfeqpNM9lj0ZoeKxThbTgE6YUgTDXINbU36HINYHwQhXKrLV2ldUQ==",
    "owner": {
    "email": "alex.originator@covata.com",
    "firstName": "Alex",
    "lastName": "Originator",
    "id": "567890123456789012"
    },
    "hasView": false,
    "canGenerateView": false,
    "mimeType": "image/jpeg",
    "originator": {
    "email": "alex.originator@covata.com",
    "id": "567890123456789012"
    },
    "labelName": "No Label",
    "shared": true,
    "contentSize": "549732",
    "parentId": "0",
    "createdAt": "2014-10-01T01:50:36.648Z",
    "modifiedAt": "2014-10-07T00:34:07.358Z",
    "type": "object",
    "labelId": "0",
    "collaborators": [
    {
    "shareStartTime": "2014-10-08T05:15:00.000Z",
    "shareEndTime": "2014-10-08T05:30:00.000Z",
    "shareParentId": null,
    "shareName": null,
    "email": "chris.collaborator@covata.com",
    "firstName": "Chris",
    "lastName": "Collaborator",
    "id": "543210987654321098"
    }
    ],
    "state": "Created"
    }