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

# Creating Secure Objects and collections

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

* [Obtain a cryptographic key](/3.0/api/creating-secure-objects-and-collections.md#obtaining-a-cryptographic-key) from the Covata Platform's Access Service, which is required for encrypting or decrypting a [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object)'s data,
* [Initialize a new 'Incomplete' Secure Object](/3.0/api/creating-secure-objects-and-collections.md#initializing-a-new-incomplete-secure-object) by associating the cryptographic key with this new Secure Object,
* [Create a completed Secure Object by encrypting its data locally](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-data-encrypted-locally), either for:

  * [Remote storage uploaded](/3.0/api/creating-secure-objects-and-collections.md#uploading-a-completed-secure-objects-encrypted-data) to and handled by the Covata Platform's Content Service, or
  * Storage handled independently by your application,
* [Create a completed Secure Object by uploading its unencrypted data](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-uploading-unencrypted-data) to the Content Service for encryption, then storage and
* [Create a 'collection'](/3.0/api/creating-secure-objects-and-collections.md#creating-a-collection-for-managing-secure-objects) for managing (groups of) Secure Objects.

> [!NOTE]
>
> * Before creating either a [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object) or a [collection](/3.0/api/creating-secure-objects-and-collections.md#collection) (collectively called an [item](/3.0/api/creating-secure-objects-and-collections.md#item)), 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](/3.0/admin/administering-users.md#a-users-roles) and/or permissions to create either:
>
>   * their own items or
>   * items within another Covata user's collection.
>
>   For more information about authenticating and authorizing Covata users to the Covata Platform, see [Authorizing your application](/3.0/api/authentication-and-authorization.md#authorizing-your-application) on the [Authentication and authorization](/3.0/api/authentication-and-authorization.md) page of this guide and the [Configuring client applications](/3.0/admin/configuring-client-applications.md) page of the [Covata Platform Administrator's Guide](/3.0/admin.md).
> * The **Supported roles (and permissions)** 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).

## Definitions

### Secure Object

A *Secure Object* (in its *Created* or 'completed' state) represents a file's data which has been encrypted (according to Covata's encryption requirements), along with the encrypted file's associated attributes/metadata (which are recorded by the Covata Platform's Access Service).

A Secure Object's content is only handled either by the Covata Platform's Content Service or externally by your application. A Secure Object's content is not handled by the Covata Platform's Access Service. However, a Secure Object's associated attributes/metadata can be retrieved from the Access Service, which in turn can assist in:

* downloading the Secure Object's content from storage (either in its encrypted or unencrypted form) from the Covata Platform's Content Service,
* obtaining the necessary key required to decrypt a Secure Object's content, which has been encrypted, handled and/or stored externally (e.g. by your application).

> [!TIP]
>
> Conceptually and in Covata's Safe Share applications, Secure Objects represent *files*.

> [!NOTE]
>
> * A Secure Object in an *Incomplete* state is one that has been [initialized](/3.0/api/creating-secure-objects-and-collections.md#initializing-a-new-incomplete-secure-object) (and associated with a [key](/3.0/api/creating-secure-objects-and-collections.md#obtaining-a-cryptographic-key)), although is not yet associated with any encrypted data (which would change the Secure Object's state to *Created*).
> * When using Covata Safe Share applications, an incomplete Secure Object could also result from a failure in either encrypting the Secure Object's data or uploading its content to storage.
> * In Covata Administration, a Secure Object's current state can be seen through the **Files** [page](/3.0/admin/administering-files.md). For more information, see the [Covata Platform Administrator's Guide](/3.0/admin.md).

### Collection

A *collection*:

* Represents a container for organizing one or more Secure Objects and/or other collections.
* Like a Secure Object, also has its own associated attributes/metadata.

Collections are:

* Analogous to an operating system's folders/directories on a file system and
* Used for logically organizing Secure Objects and other collections. The Covata Platform's Content Service uses collections for this purpose.

> [!TIP]
>
> In Covata's Safe Share applications, collections represent *folders*.

### Item

An *item* (in the context of Secure Objects and collections) is a generic term that refers to either a [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object) or a [collection](/3.0/api/creating-secure-objects-and-collections.md#collection).

Every item, regardless of whether it is a Secure Object or a collection has a *unique identifier* (or ID).

## Obtaining a cryptographic key

A cryptographic key is required to encrypt data into a complete [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object).

To obtain a cryptographic key from the Covata Platform's Access Service (which is the first step before creating a new Secure Object), make a `POST` request to the [\<access-service>/api/v1/keys](/3.0/api/access-service-api-v1-keys.md) API endpoint with a [JSON](http://json.org/) object in the body of the request that either:

* contains the optional **keyLength** parameter (as a name/value pair) which determines the bit length of the cryptographic key to be returned from the Covata Platform. Specify a value of `128`, `192` or `256`. \

  *OR*
* is empty. Specifying an empty JSON object implicitly sets the **keyLength** parameter's value to `256`.

**Example request:** Initiating a request to obtain a cryptographic key:

```bash theme={null}
curl https://access-service.xy-company.com/api/v1/keys \
    -H 'Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6' \
    -H 'Content-Type: application/json' \
    -d '{}' \
    -X POST
```

> [!NOTE]
>
> As indicated in this example, the access token obtained when you [authorized your application](/3.0/api/authentication-and-authorization.md#authorizing-your-application) must be included in the header of this request (as the bearer token) for the request to succeed.

If your request (above) was sent successfully, the Covata Platform responds by sending back a JSON object containing the key's ID value (required to associate a cryptographic key with a Secure Object), other information about the key's characteristics and a date and time stamp of when the key was created.

**Example response:** Response from the Covata Platform upon successfully processing a client application's request for a cryptographic key:

```json theme={null}
{
  "keys": [
    {
      "id": "123456789012345678",
      "keyValue": "2VCZkPeYPhvL4VkzrEqIVGaW2AGmRM1uwuXiPRbe8NU=",
      "initializationVector": "fpEIYIk+dnMw7rgFA+Bz8g==",
      "cryptographicAlgorithm": "AES",
      "keyLength": 256,
      "createdAt": "2014-09-24T06:08:40.416Z",
      "modifiedAt": "2014-09-24T06:08:40.416Z"
    }
  ]
}
```

**Next step:** Now that you have a cryptographic key, you can begin the process of creating a new Secure Object. This involves either:

* [Initializing a new 'Incomplete' Secure Object](/3.0/api/creating-secure-objects-and-collections.md#initializing-a-new-incomplete-secure-object), which allows you to encrypt the Secure Object's data (thereby changing its state to *Created*) in a separate/subsequent request.
* [Creating a completed Secure Object (data encrypted locally)](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-data-encrypted-locally), which initializes and completes the Secure Object (by associated the Secure Object with its locally encrypted data) in a single request.

## Initializing a new 'Incomplete' Secure Object

Initializing a new Secure Object (whose state is *Incomplete*):

* associates the cryptographic key with a new Secure Object, which results in an incomplete Secure Object and
* is a requirement for (and often the first step in) creating the Secure Object itself.

To do this, make a `POST` request to the [\<access-service>/api/v1/objects](/3.0/api/access-service-api-v1-objects.md) API endpoint with a JSON object in the body of the request that contains the **keyId** parameter (as a name/value pair) whose value is the ID of the key ([obtained above](/3.0/api/creating-secure-objects-and-collections.md#obtaining-a-cryptographic-key)).

The *ID of the incomplete Secure Object* is returned in the response to this request.

> [!TIP]
>
> Your application may wish to temporarily store this ID value as it is used for completing a Secure Object, either by [locally encrypting its data](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-data-encrypted-locally) and then [uploading it for storage](/3.0/api/creating-secure-objects-and-collections.md#uploading-a-completed-secure-objects-encrypted-data), or by [uploading its unencrypted data for encryption and storage](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-uploading-unencrypted-data).

**Next step:** Now that you have initialized your Secure Object, you can begin encrypting its data. Depending on your application's requirements, this involves either:

* [Creating a completed Secure Object (data encrypted locally)](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-data-encrypted-locally), whose encrypted data can then be either uploaded to remote storage (via the Covata Platform's Content Service) or handled independently by your application.
* [Creating a completed Secure Object (uploading unencrypted data)](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-uploading-unencrypted-data), whose unencrypted data can then be uploaded for encryption by the Content Service, which in turn transfers the encrypted data to remote storage. \

  **Choosing which of these approaches is right for you** \

  The connection between a client's machine (that stores locally unencrypted data) and the Covata Platform's Content Service (which can encrypt this data) is secured using HTTPS. \

  However, if you do not wish a Secure Object's locally stored data to be sent from the client's machine *over any type of connection* in its unencrypted form, your application can encrypt this data on the client machine first and then upload the encrypted data to remote storage via the Content Service, or store it elsewhere. \

  Alternative solutions for storing a Secure Object's encrypted data to that provided by the Covata Platform's Content Service are beyond the scope of this documentation.

## Creating a completed Secure Object (data encrypted locally)

Creating a completed [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object) from locally-encrypted data involves the following steps:

1. Ensuring you [obtained a cryptographic key](/3.0/api/creating-secure-objects-and-collections.md#obtaining-a-cryptographic-key) for the Secure Object (and optionally, [initialized the Secure Object](/3.0/api/creating-secure-objects-and-collections.md#initializing-a-new-incomplete-secure-object) with this cryptographic key).
2. Using this cryptographic key to encrypt the Secure Object's data locally and obtaining the [SHA-512](http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf) value of this encrypted data.
3. Associating this encrypted data with the Secure Object by assigning this SHA-512 value to the Secure Object. This step 'completes' the Secure Object, which changes its state from *Incomplete* to *Created*. \

   **Note:** If the Secure Object was not initialized earlier, it can be both initialized and completed during this step.

**Requirements for encrypting data locally**

When encrypting your data using the cryptographic key ([obtained above](/3.0/api/creating-secure-objects-and-collections.md#obtaining-a-cryptographic-key)), then ensure that this data is encrypted using:

* The AES algorithm (in CBC mode) with [PKCS #7 padding](http://tools.ietf.org/html/rfc2315) (see [\<access-service>/api/v1/keys](/3.0/api/access-service-api-v1-keys.md) for more information), as well as
* Both the [cryptographic key and initialization vector](/3.0/api/access-service-api-v1-keys.md#access-service-api-v1-keys-returns) (returned by calling the [\<access-service>/api/v1/keys](/3.0/api/access-service-api-v1-keys.md) API endpoint) for this Secure Object.

If you do not follow these requirements, then either your attempt to upload your encrypted data may fail or if successful, any attempt to [download](/3.0/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-GET) the Secure Object's data in its decrypted form will result in the retrieval of garbled data.

**Completing the Secure Object**

To complete a Secure Object (whose state is *Created*) from its locally encrypted data, make either a:

* `PUT` request to the [\<access-service>/api/v1/objects/\{objectId}](/3.0/api/access-service-api-v1-objects-objectid.md) endpoint with:

  * the ID of the incomplete Secure Object (obtained in the response for [initializing the Secure Object above](/3.0/api/creating-secure-objects-and-collections.md#initializing-a-new-incomplete-secure-object)) in this request's URL \

    and
  * a JSON object in the body of this request that contains the **sha512** parameter (name/value pair) whose value is the SHA-512 value of locally encrypted data.

  *OR*
* `POST` request to the [\<access-service>/api/v1/objects](/3.0/api/access-service-api-v1-objects.md) API endpoint with a JSON object in the body of the request that contains:

  * the **keyId** parameter (as a name/value pair) whose value is the ID of the key ([obtained above](/3.0/api/creating-secure-objects-and-collections.md#obtaining-a-cryptographic-key)) \

    and
  * the **sha512** parameter (name/value pair) whose value is the SHA-512 of the locally encrypted data,

In both of these cases, a SHA-512 value must be associated with the Secure Object to set its state to *Created*.

**Next step:** Depending on your application's requirements, follow one of these procedures:

* [Uploading a completed Secure Object's encrypted data](/3.0/api/creating-secure-objects-and-collections.md#uploading-a-completed-secure-objects-encrypted-data)
* [Creating a collection for managing Secure Objects](/3.0/api/creating-secure-objects-and-collections.md#creating-a-collection-for-managing-secure-objects)

## Uploading a completed Secure Object's encrypted data

Once a [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object)'s data has been encrypted locally ([above](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-data-encrypted-locally)) and the Secure Object's state has changed to *Created*, your application can send this encrypted data to remote storage via the Covata Platform's Content Service.

To upload a completed Secure Object's encrypted data to the Content Service, make a `POST` request to the [\<content-service>/api/v1/objects/\{objectId}/contents](/3.0/api/content-service-api-v1-objects-objectid-contents.md) API endpoint, along with the actual encrypted data to be uploaded.

When making this request, the value of the **format** URL parameter must be `encrypted`. See [Required parameters on POST](/3.0/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) of [\<content-service>/api/v1/objects/\{objectId}/contents](/3.0/api/content-service-api-v1-objects-objectid-contents.md) for more information.

> [!NOTE]
>
> If the data being uploaded is larger than the upload *chunk size* permitted by the Covata Platform (whose default value is 10 [mebibytes](http://physics.nist.gov/cuu/Units/binary.html)), then the data must be uploaded in multiple requests to this endpoint. For more information, see [Required parameters for multi-chunk uploads](/3.0/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) of [\<content-service>/api/v1/objects/\{objectId}/contents](/3.0/api/content-service-api-v1-objects-objectid-contents.md).

**Next step:** Depending on your application's requirements, follow one of these procedures:

* [Creating a collection for managing Secure Objects](/3.0/api/creating-secure-objects-and-collections.md#creating-a-collection-for-managing-secure-objects)

## Creating a completed Secure Object (uploading unencrypted data)

Creating a completed [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object) from unencrypted data stored locally involves the following steps:

1. Ensuring you [obtained a cryptographic key](/3.0/api/creating-secure-objects-and-collections.md#obtaining-a-cryptographic-key) for the Secure Object and [initialized the Secure Object](/3.0/api/creating-secure-objects-and-collections.md#initializing-a-new-incomplete-secure-object) with this cryptographic key.
2. Uploading the Secure Object's unencrypted data to remote storage via the Content Service. This step 'completes' the Secure Object, which changes its state from *Incomplete* to *Created*.

To upload an *incomplete* Secure Object's *unencrypted* data to the Content Service, make a `POST` request to the [\<content-service>/api/v1/objects/\{objectId}/contents](/3.0/api/content-service-api-v1-objects-objectid-contents.md) API endpoint, along with the actual unencrypted data to be uploaded.

However, when making this request, the value of the **format** URL parameter must be `plaintext`. See [Required parameters on POST](/3.0/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) of [\<content-service>/api/v1/objects/\{objectId}/contents](/3.0/api/content-service-api-v1-objects-objectid-contents.md) for more information.

> [!NOTE]
>
> If the data being uploaded is larger than the upload *chunk size* permitted by the Covata Platform (whose default value is 10 [mebibytes](http://physics.nist.gov/cuu/Units/binary.html)), then the data must be uploaded in multiple requests to this endpoint. For more information, see [Required parameters for multi-chunk uploads](/3.0/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) of [\<content-service>/api/v1/objects/\{objectId}/contents](/3.0/api/content-service-api-v1-objects-objectid-contents.md).

After completing all required requests to upload the unencrypted data, the Content Service automatically:

1. Encrypts the data.
2. Calculates the [SHA-512](http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf) value of this encrypted data.
3. Transfers the encrypted data to remote storage.
4. Associates this SHA-512 value with the Secure Object, which:

   * is returned in the response to the last upload request (see [Returns from a POST request](/3.0/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-returns-from-a-POST-request) of [\<content-service>/api/v1/objects/\{objectId}/contents](/3.0/api/content-service-api-v1-objects-objectid-contents.md)) and
   * completes the Secure Object (changing its state from *Incomplete* to *Created*).

> [!NOTE]
>
> For a multi-chunk upload, steps 1 to 3 above are conducted for each chunk and after the last chunk has been uploaded, the final SHA-512 value (for the entire encrypted data) is calculated and associated with the Secure Object.

**Next step:** Depending on your application's requirements, follow one of these procedures:

* [Creating a collection for managing Secure Objects](/3.0/api/creating-secure-objects-and-collections.md#creating-a-collection-for-managing-secure-objects)

## Creating a collection for managing Secure Objects

[Collections](/3.0/api/creating-secure-objects-and-collections.md#collection) are used for logically organizing Secure Objects and other collections, which the Covata Platform's Content Service utilizes for organise files and folders for Covata users.

To create a collection, make a `POST` request to the [\<access-service>/api/v1/collections](/3.0/api/access-service-api-v1-collections.md) API endpoint with the **name** of the collection and the **parentId** value, both of which are parameters (each specified as name/value pairs) within a JSON object in the body of the request. The **parentId** value should be:

* `0` to specify that the new collection will be created at the logical root level, or
* the ID value of the collection that will become the parent of this new collection. For more information about retrieving an existing collection, see retrieving-an-existing-collection.

> [!TIP]
>
> A new Secure Object can be created within an existing collection by specifying the **parentId** value when making the appropriate API endpoint call to either:
>
> * [Initialize](/3.0/api/creating-secure-objects-and-collections.md#initializing-a-new-incomplete-secure-object) the Secure Object or
> * [Complete](/3.0/api/creating-secure-objects-and-collections.md#creating-a-completed-secure-object-data-encrypted-locally) the Secure Object by encrypting its data locally.
>
> If a Secure Object's unencrypted data is to be uploaded to the Covata Platform's Content Service, specify the **parentId** value when initializing the Secure Object.


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