Create encryption key (generate or import)
Request to create a new encryption key:
POST /api/v2/encrypt_keys.json
The request body contains the encryption key object. The
add_type attribute selects whether a new key pair is generated or an existing one is imported.
Generate a new key
Set add_type to generate (the default) and, optionally, key_length:
{
"encrypt_key": {
"name": "Acme 2026",
"tenant_id": "11111111-1111-1111-1111-111111111111",
"is_active": true,
"protection_mode": "user",
"add_type": "generate",
"key_length": 2048
}
}
Import an existing key
Set add_type to import and provide public_key. private_key and private_key_password are
optional:
{
"encrypt_key": {
"name": "Acme 2026",
"tenant_id": "11111111-1111-1111-1111-111111111111",
"is_active": true,
"add_type": "import",
"public_key": "MIGfMA0GCSqGSIb3DQEBAQ...",
"private_key": "RheQwd3Y6cdLyH4MFMxN61K6K/lyoyB...",
"private_key_password": "secret"
}
}
Import without a private key
When you import a public key only, MiaRec can encrypt recordings with it but nobody on this server can decrypt them, including root administrators. To play them back, transfer the recordings to another MiaRec server that holds the private key. Use this setup when a hosted provider records calls that only the customer's premises may decrypt.
The API user must have a key pair of their own (created when the user's password is set through
the web portal or the API), because the private key of the new encryption key is protected with
it. Otherwise the request fails with 400 Bad Request and the error InvalidGeneral.
Response contains HTTP status code as shown in the following table.
| Response | Description |
|---|---|
| 201 Created | The encryption key has been successfully created. The |
| Location: /api/v2/encrypt_keys/e011c408-f288-11e4-9b73-e03f497dbdff.json |
{"url": "/api/v2/encrypt_keys/e011c408-f288-11e4-9b73-e03f497dbdff.json"} | | 400 Bad Request |
The request cannot be completed because the supplied JSON object has invalid data, the key material cannot be decoded, or the API user has no key pair ({"error": "InvalidGeneral", "explanation": "Could not add encryption key", "details": "Could not save new encryption key because your account doesn't have user's public key. ..."}).
The response contains a detailed description of the error, like:
{"error": "InvalidRecord", "explanation": "Record Validation errors", "details": {"public_key": "Public key is not valid"}}