> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocoondata.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

## URL structure&#x20;

```text theme={null}
https://access-service.xy-company.com/api/v1/objects/{objectId}
```

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

## Supported methods and overview&#x20;

* `GET` - used to retrieve information about a [Secure Object](/3.1/api/creating-secure-objects-and-collections.md#secure-object), based on the Secure Object's ID.
* `PUT` - used to modify a Secure Object's attributes/metadata, which involves the owner<sup>1</sup> of this Secure Object performing *any combination* of the following:

  * Modifying the collaborators (as well as their [permission sets](/3.1/api/access-service-api-v1-permissions-sets.md)) 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.

<sup>1</sup> A Secure Object's owner is the [Covata user](/3.1/admin/administering-users.md) whose account was used to [initialize/create the Secure Object](/3.1/api/access-service-api-v1-objects.md). (A Secure Object's ownership [can also be changed](/3.1/api/content-service-api-v1-items-transfer.md) to that of another Covata user.)

## Detailed description&#x20;

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](/3.1/api/access-service-api-v1-items.md) 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 owner<sup>2</sup> to modify the Secure Object's attributes/metadata, which include the following:

  * Label (specified through this endpoint's **labelId** [parameter](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)) - defines which groups of [Covata users](/3.1/admin/administering-users.md) 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](/3.1/api/access-service-api-v1-permissions-sets.md) (specified through this endpoint's **collaborators** [parameter](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)) - 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](/3.1/api/access-service-api-v1-permissions-sets.md):

      * **Download** the Secure Object's content (by calling the `GET` method on the [\<content-service>/api/v1/objects/\{objectId}/contents](/3.1/api/content-service-api-v1-objects-objectid-contents.md) endpoint).
      * **Print** and **View** the Secure Object's content from a Safe Share application's [content viewer](/3.1/user/accessing-secure-content.md#viewing-and-printing-secure-content). 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](/3.1/api/content-service-api-v1-objects-objectid-view.md) endpoint).
    * **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](/3.1/api/content-service-api-v1-objects-objectid-contents.md) 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 owner<sup>2</sup> 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](/3.1/api/access-service-api-v1-objects.md) 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](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-required-headers) of requests to this endpoint. Therefore, it is advised that you first explicitly [delete this data in storage](/3.1/api/content-service-api-v1-objects-objectid-contents.md) *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](/3.1/api/access-service-api-v1-users-userid.md).

<sup>2</sup> A Secure Object's owner is the Covata user whose account was used to [initialize/create the Secure Object](/3.1/api/access-service-api-v1-objects.md). (A Secure Object's ownership [can also be changed](/3.1/api/content-service-api-v1-items-transfer.md) to that of another Covata user.)

## Supported roles and conditions&#x20;

This API endpoint supports the following Covata user [roles](/3.1/admin/administering-users.md#a-users-roles) (as described in the [Covata Platform Administrator's Guide](/3.1/admin.md)), conditions and [permissions](/3.1/api/access-service-api-v1-permissions-sets.md) (where applicable):

* [Originator](/3.1/admin/administering-users.md#originator-role) - a Covata user with this role can call the `GET`, `PUT` and `DELETE` methods on a Secure Object they own.
* **Originator**, [Collaborator](/3.1/admin/administering-users.md#collaborator-role) and [Ad hoc](/3.1/admin/administering-users.md#adhoc-role) - 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](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-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](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-required-headers) of requests to this endpoint.

## Required headers&#x20;

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&#x20;

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](/3.1/api/access-service-api-v1-permissions-sets.md) 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](/3.1/api/access-service-api-v1-permissions-sets.md) 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 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](/3.1/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) the Secure Object's *unencrypted* data to storage via the Covata Platform's Content Service, then *omit this parameter*. When you make the [upload](/3.1/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) 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](/3.1/api/creating-secure-objects-and-collections.md#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](/3.1/api/creating-secure-objects-and-collections.md#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](/3.1/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) 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](/3.1/api/access-service-api-v1-objects.md#access-service-api-v1-objects-optional-parameters-on-POST) (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):**

  ```json theme={null}
  {
    "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](/3.1/api/access-service-api-v1-permissions-sets.md) 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&#x20;

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](/3.1/api/access-service-api-v1-objects.md#access-service-api-v1-objects-optional-parameters-on-POST), or [last updated](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters). This value is `null` if the **name** was never specified.
* **sha512** - The unique [SHA-512](http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf) 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](/3.1/admin/administering-users.md) page of Covata Administration and the [My Account](/3.1/user/managing-your-account.md) 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](/3.1/user/accessing-secure-content.md#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](/3.1/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) *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](/3.1/api/access-service-api-v1-objects.md#access-service-api-v1-objects-optional-parameters-on-POST), or [last updated](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters). 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](/3.1/api/access-service-api-v1-objects.md#access-service-api-v1-objects-optional-parameters-on-POST), or [last updated](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters). 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](/3.1/api/creating-secure-objects-and-collections.md#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](/3.1/api/access-service-api-v1-objects.md) 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](/3.1/api/access-service-api-v1-objects.md#access-service-api-v1-objects-optional-parameters-on-POST), or [last updated](/3.1/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters). 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](/3.1/admin/administering-users.md) page of Covata Administration and the [My Account](/3.1/user/managing-your-account.md) 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):**

  ```json theme={null}
  {
    "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"
  }
  ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.