Introduction

Ubiq API

The Ubiq API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Ubiq Platform uses API Key Credentials to authenticate encryption / decryption requests generated at the application layer from Ubiq Client Libraries. The Client Libraries are downloadable from GitLab repositories, lightweight and language-specific.

📘

Your Data Remains Your Data

The Ubiq Platform never intercepts, sees or stores your data – Ever!

API Key Credentials

An API Key Credential is comprised of three values. These values will correspond and provide access to a single Application Master Key. Many different API Key Credentials can correspond to the same Application Master Key.

There are three (3) elements that make up the API Key Credentials:

ACCESS_KEY_ID - A globally unique public identifier used to help distinguish different API Keys.

SECRET_SIGNING_KEY - A shared secret value and is used for signing and verifying requests from the client libraries to the Ubiq Platform REST API services. This value should be considered secret and treated and protected like a password. This value cannot be recovered if lost. If this value is lost, then the corresponding API Key Credentials should be deleted and a new one created.

SECRET_CRYPTO_ACCESS_KEY - A secret value used when encrypting data encryption keys passed between Ubiq's cryptographic service and the Client Libraries. This key value is generated on the client and only ever stored on the client. This value should be considered secret and treated and protected like a password. This value cannot be recovered if lost. If this value is lost, then the corresponding API Key Credentials should be deleted and a new one created.

🚧

The API Key Credentials carry many privileges, so be sure to keep them secure! Do not share these credentials in any publicly accessible areas such as GitHub, GitLab, client-side source code, and so forth.

API Requests

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

You embed the Ubiq Client Library within your application. When a Ubiq API request is made for an encryption or decryption call, then the Ubiq Platform:

  1. Authenticates the API call with the API Key Credentials and, if valid,
  2. Retrieves the Registered Application Master Encryption Key from Ubiq's cryptographic service, creates a unique data encryption key, and
  3. Passes the Data Encryption Key back to the client for use to encrypt, or decrypt, application data.

Rotating Application Master Keys

When you rotate an Application's Master Key, either manually, or on a schedule, there is no need to regenerate API Key Credentials. The API Key Credentials float with the new Application Master Key and will continue to work to create data encryption keys to encrypt and decrypt your data. Additionally, when previously encrypted data is decrypted, it will continue to use the old Application Master Key to regenerate the old data encryption keys for decryption of that data; however, new encryption calls will use the new Application Master Key to generate the data encryption keys to encrypt new data (or to re-encrypt old data). The Ubiq Platform takes care of all this complex associated key management for you in the background.

Rolling API Keys

When you Roll an API Key, there is no need to regenerate the Application Master Key. The replacement API Key Credentials will automatically be associated with the original Application Master Key.