<access-service>/api/v1/keys

​

URL structure

https://access-service.xy-company.com/api/v1/keys

​

Supported methods and overview

• POST - used to generate a cryptographic key.

​

Detailed description

​

Supported roles and conditions

• Originator
• Collaborator and Ad hoc - a Covata user with either of these roles should only call this endpoint when they intend to create a Secure Object within a collection that this user has the File Upload permission on.

​

Required headers

• Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
  where the Bearer token is the appropriate access token.
• Content-Type: application/json

​

Optional parameters

• 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 whose mode of operation is CipherBlock Chaining (CBC). Valid values for this parameter are: 128, 192 or 256. If this parameter is not specified, a value of 256 is assumed. Example:
  { "keyLength": 128 }
  

​

Required body

• {}

​

Returns

• 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, or
  • if the key needs to be deleted 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 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 (see <access-service>/api/v1/objects 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 (see <access-service>/api/v1/objects 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 above.
• createdAt - The date and time when the cryptographic key was created.
• modifiedAt - This value should match the createdAt value above. Example:
  {
    "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"
      }
    ]
  }