Skip to content

Create encrypt key (generate or import)

Generate new encryption key

To automatically generate new encryption key, submit the following POST request with JSON-formatted data.

POST /api/v2/encrypt_keys.json

HTTP body should contain JSON-formatted data with the following parameters:

Field Type Description
name string Human-readable encrypt key name.
tenant_id UUID ID of tenant, for which the encrypt key will be created. This field is ignored when multi-tenancy is disabled in MiaRec.
protection_mode string

This parameter specified whether the key is protected with user's credentials or application credentials.

When a key is protected with user's credentials, it is necessary to explicitly grant users access to this key.

App-protected mode is required when SAML 2.0 Single Sign-On or speech analytics is used.

Supported values:

  • user - protect the key with user's credentials (default)
  • app - protected the key with application credentials
add_type string

This parameter specified whether the key is generated or imported.

Supported values:

  • generate - generate new random key
  • import - import existing key
is_active boolean If true, then the new key will be used for encrypting of all on-going recordings for that tenant. If false, then the key will be used only for accessing previously encrypted recordings with that key.
key_length integer

Length of encryption key in bits.

Supported values:

  • 1024
  • 2048 (default, recommended)
  • 4096

Example of JSON data to submit:

{
    "encrypt_key":
    {
        "name": "New encrypt key"
        "is_active": true,
        "add_type": "generate",
        "key_lenght": 2048,
    }
}

Import encryption key

To import existing encryption key, submit the following POST request with JSON-formatted data.

POST /api/v2/encrypt_keys.json

HTTP body should contain JSON-formatted data with the following parameters:

Field Type Description
name string Human-readable encrypt key name.
tenant_id UUID ID of tenant, for which the encrypt key will be created. This field is ignored when multi-tenancy is disabled in MiaRec.
add_type string

This parameter specified whether the key is generated or imported.

Supported values:

  • generate - generate new random key
  • import - import existing key
is_active boolean If true, then the new key will be used for encrypting of all on-going recordings for that tenant. If false, then the key will be used only for accessing previously encrypted recordings with that key.
public_key string RSA public key formatted in Base64 encoding (PEM format).
private_key string

RSA private key formatted in Base64 encoding (PEM format).

This parameter is optional. If you do not provide private key, then the imported encryption key will be used only for encryption of audio files without ability to decrypt them. Users will not be able to decrypt these recordings on that server. To playback such recordings, you will need to transfer these recordings to another MiaRec server, which has the corresponding private key. This is an advanced feature of MiaRec - it allows to deploy a recording server in one location and a playback server in another location. For example, the hosted service provider may record customer calls directly into encrypted format and nobody on service provider site will be able to playback those recordings, including root administrators. Data should be uploaded to customer premises, where only authorized persons will be able to playback them.
private_key_password string Password for decrypting private key, if the latter has been exported previously with password protection.

Example of JSON data to submit:

{
    "encrypt_key":
    {
        "name": "New encrypt key"
        "is_active": true,
        "add_type": "import",
        "public_key": "MIGfMA0GCSqGSIb3DQEBAQ...",
        "private_key": "RheQwd3Y6cdLyH4MFMxN61K6K/lyoyB...",
        "private_key_password": "secret"
    }
}

Response values

Response contains HTTP status code as shown in the following table.

Response Description
201 Created

Encrypt key record has been successfully created. HTTP header Location contains URL by which the newly created object should be know.

For example:

HTTP/1.1 201 Created Location: /api/v2/encrypt_keys/e011c408-f288-11e4-9b73-e03f497dbdff.json
403 Forbidden The request cannot be completed because API user has no permission to create encrypt keys
400 Bad Request

The request cannot be completed because supplied JSON object has invalid data.

When response has content type application/json, then it contains more detailed description of error in JSON format like:

{"error": "InvalidRecord","description": "Record Validation errors","details": ["key_length": "ke_lenght should one of 1024, 2048 or 4086"]}