> ## 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/keys

## URL structure&#x20;

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

## Supported methods and overview&#x20;

* `POST` - used to generate a cryptographic key.

## Detailed description&#x20;

This API endpoint generates a cryptographic key, which in turn is required to encrypt data into a [Secure Object](/3.0/api/creating-secure-objects-and-collections.md#secure-object).

## Supported roles and conditions&#x20;

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

* [Originator](/3.0/admin/administering-users.md#originator-role)
* [Collaborator](/3.0/admin/administering-users.md#collaborator-role) and [Ad hoc](/3.0/admin/administering-users.md#adhoc-role) - a Covata user with either of these roles should only call this endpoint when they intend to [create a Secure Object](/3.0/api/access-service-api-v1-objects.md) within a [collection](/3.0/api/creating-secure-objects-and-collections.md#collection) that this user has the **File Upload** *permission* on.

The Covata Platform's resources available to one of these Covata users (above) is determined by the access token passed in the [header](/3.0/api/access-service-api-v1-keys.md#access-service-api-v1-keys-required-headers) of requests to this endpoint.

## Required headers&#x20;

* `Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6` \

  where the `Bearer` token is the appropriate access token.
* `Content-Type: application/json`

## Optional parameters&#x20;

The following optional parameter can be sent in the body of the POST request, as an individual member of a JSON object:

* **keyLength** - The bit length of the cryptographic key to be returned from the Covata Platform. This key is used to encrypt data using an [Advanced Encryption Standard (AES) cryptographic algorithm](http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf) whose mode of operation is [CipherBlock Chaining (CBC)](http://csrc.nist.gov/publications/fips/fips81/fips81.htm). Valid values for this parameter are: `128`, `192` or `256`. If this parameter is not specified, a value of `256` is assumed.

  **Example:**

  ```json theme={null}
  { "keyLength": 128 }
  ```

## Required body&#x20;

If none of the [Optional parameters](/3.0/api/access-service-api-v1-keys.md#access-service-api-v1-keys-optional-parameters) above are specified, then an empty JSON object must be passed in the body of the request:

* `{}`

## Returns&#x20;

A JSON-formatted response containing a `keys` array which has the following elements:

* **id** - The ID value associated with the cryptographic key value returned below. \

  **Important:** Retain this value as it is required during the initial stages of creating a Secure Object - i.e. this key ID value is used:

  * to [associate the cryptographic key with the Secure Object itself](/3.0/api/access-service-api-v1-objects.md), or
  * if the [key needs to be deleted](/3.0/api/access-service-api-v1-keys-keyid.md) as a result of the association between the cryptographic key and Secure Object failing.
* **keyValue** - The cryptographic key value itself. The length of this key may differ depending on the `keyLength` value submitted as part of the request's [optional parameters](/3.0/api/access-service-api-v1-keys.md#access-service-api-v1-keys-optional-parameters) above. \

  **Note:** This value is returned for the purposes of local/client-side encryption (i.e. if your client application does not rely on the Covata Platform's server-side encryption). The **keyValue** value should be retained by your client application after associating this key with an [initialized Secure Object](/3.0/api/access-service-api-v1-objects.md#access-service-api-v1-objects-required-parameters-on-POST) (see [\<access-service>/api/v1/objects](/3.0/api/access-service-api-v1-objects.md) for more information), until you have performed local/client-side encryption.
* **initializationVector** - The initialization vector required to begin local/client-side encryption using the AES algorithm (in CBC mode). \

  **Note:** Like **keyValue** above, this value is also returned for the purposes of local/client-side encryption. The **initializationVector** value should be retained after associating **keyValue** (above) with an [initialized Secure Object](/3.0/api/access-service-api-v1-objects.md#access-service-api-v1-objects-required-parameters-on-POST) (see [\<access-service>/api/v1/objects](/3.0/api/access-service-api-v1-objects.md) for more information), until you have performed local/client-side encryption.
* **cryptographicAlgorithm** - The cryptographic algorithm supported by the Covata Platform. This should be `AES`.
* **keyLength** - The bit length of the cryptographic key value returned above. This should be `256` or match the value of the `keyLength` submitted as part of the request's [optional parameters](/3.0/api/access-service-api-v1-keys.md#access-service-api-v1-keys-optional-parameters) above.
* **createdAt** - The date and time when the cryptographic key was created.
* **modifiedAt** - This value should match the `createdAt` value above.

  **Example:**

  ```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"
      }
    ]
  }
  ```


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