URL structure

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

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

Supported methods and overview

GET - retrieves the cryptographic key required to decrypt the read-only view of the active version of a file object/Secure Object (specified by objectId).

Note: This method takes no parameters.

Detailed description

This API endpoint retrieves the cryptographic key required to decrypt the read-only view of the active version of a file object (specified by objectId).

This key is automatically generated after uploading a file object's data to storage (via the <content-service>/api/v1/objects/{objectId}/contents API endpoint) and both of the following criteria have been met:

The file object's file name (i.e. its name value) contains an extension which is supported by the SafeShare content viewer.
The size of the file in its unencrypted form (i.e. its contentSize value) is less than the default of 20,000,000 bytes.

A file object's ID can be obtained by calling the <access-service>/api/v1/organisations/{orgId}/items API endpoint, which retrieves a list of information associated with file objects that can be filtered using various 'search' criteria.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

Originator - when this user owns the file object whose ID is specified by {objectId} in the request's URL.
Originator, Collaborator and Ad hoc - when this user is a collaborator with the View permission on the file object whose ID is specified by {objectId} in the URL.

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response containing the following members is also returned:

keyValue - The cryptographic key value itself.
cryptographicAlgorithm - The cryptographic algorithm supported by the Cocoon Data Platform. This should be AES.
keyLength - The bit length of the cryptographic key value returned above.
initializationVector - The initialization vector required to begin local/client-side encryption using the AES algorithm (in CBC mode).
Example:
{

"keyValue": "2VCZkPeYPhvL4VkzrEqIVGaW2AGmRM1uwuXiPRbe8NU=",

"cryptographicAlgorithm": "AES",

"keyLength": 256,

"initializationVector": "fpEIYIk+dnMw7rgFA+Bz8g=="

}