Understanding Shield API

You will know more about the APIs that support Shield features and functionalities.

API Definition

Shield supports API access to the functionality described below. API access is restricted to Shield administrators. Detailed Swagger-based API documentation is available here. This documentation is updated automatically with releases and patches to ensure it is always up to date with the current API implementation.

An important feature of Shield is key rotation. Key rotation refers to when existing content is re-encrypted using the latest key. A new key is frequently created before key rotation is initiated. This is useful when a key may have been compromised. The data encryption service retains multiple keys (the current and previous keys) so it is still able to decrypt content using the older keys. Initial encryption and subsequent re-encryption of data is run as a background job as large collections can take time to complete.

Encryption Key Management

Encryption keys are secrets used to encrypt and decrypt data. Shield gives you control over the management of your keys to help with your organization’s compliance obligations. The API allows Shield administrators to:
  • Create a new encryption key
  • Retrieve details of an encryption key or all encryption keys
  • Update metadata of a given encryption key such as its rotation period
  • Delete unused encryption keys

Data Encryption Management

Once encryption keys are defined, data can be encrypted/decrypted using those keys. The API allows Shield administrators to:
  • Activate data encryption, including setting access rights to who can decrypt the data
  • Update access rights on previously encrypted data
  • Change the encryption key used to encrypt new data
  • Re-encrypt (as a background job) data with a new key
  • Disable encryption, decrypting data to its original unencrypted form
  • Check background encryption job status (started, in progress, completed)

Reading the Detailed API Documentation

The following images are examples of Reltio’s Swagger-generated documentation. At the top of the page is a summary of the API.

Each HTTP verb and endpoint is then documented, including the URL structure, example response, and supported response codes. POST and PUT requests include the required structure of the request body. You can also try out the API call.

The documentation covers multiple endpoints. Click on a definition to expand. For example, click on Encryption API to see the API definition on generation of an encryption key.