Skip to content

Importing a private key via API (PKCS #8)

The imports function allows you to programmatically import private keys with their corresponding certificates into the TLS Protect Cloud platform. This feature allows customers to import private keys and certificates that would enable them to use the Push Provisioning feature for non-ASK certificates and would also allow them to use TLS Protect Cloud as an enterprise vault for their machine identities.


Before attempting this import, ensure you have added your corresponding certificate chain into a trusted CA certificate in TLS Protect Cloud. Learn more about Trusted CA Certificates.

Before you begin

Having knowledge of Data Encryption Key (DEK) encryption is a prerequisite for this API. To learn more about DEK encryption, see our docs.

Some things to note in the POST request:

  • If a value in passwordEncryptedPrivateKey is provided, a value in the dekEncryptedPassword field must also be provided. Refer to this Recipe to learn how to encrypt the password.

  • If a value in dekEncryptedPrivateKey is provided , a value in dekEncryptedPassword field is not needed.

  • passwordEncryptedPrivateKey refers to a PKCS #8 private key encrypted by a password.

  • dekEncryptedPrivateKey refers to a PKCS #8 private key encrypted by the DEK (not by the password).

  • The values for encryptionKeyId & edgeInstanceId must be provided for the imports function to work.


Private keys must be in PKCS #8 format and encrypted. Both the keys and X.509 certificates must be PEM encoded. Also, there is a limit of 100 keys per API call. The API will respond with an error if you input more than 100 keys.

To import a list of certificates and their corresponding private keys

  1. If you have not already done so, obtain an API key.

  2. Use the imports function to import up to 100 private keys in a single API call. For example:


  3. In the JSON body, insert the appropriate values. Note that importInformation is an array, and it can have multiple objects. Each object represents a key and related information. For example:


    You can run the GET /v1/edgeinstances call to retrieve the edgeInstanceId and encryptionKeyId values that you will need below. Note in the GET /v1/edgeinstances response you will use id in the edgeinstances object for the edgeInstanceId.

     GET /v1/edgeinstances/ HTTP/1.1 
     tppl-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    Example request

      "edgeInstanceId": "<your edgeInstanceId>",
      "encryptionKeyId": "<your encryptionKeyId>",
      "importInformation": [
          "certificate": "<pem>",
          "passwordEncryptedPrivateKey": "<pem>",
          "dekEncryptedPrivateKey": "<base64 encoded string>",
          "dekEncryptedPassword": "BNSr0IAm9uFrCPbz78AbB/XeNBwT4h6raWX6EEuEtzuoaKRYtV3QGShQP0islB1Gnrt34XeQa5Is"

    Example response

    HTTP 201 Created
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "creationDate": "2022-11-11T16:34:41.666Z"

    The response will return the job id, which you will use to check the import status below. There is a limit of 100 keys per API call. The API will respond with an error if you input more than 100 keys.

    Check the status of the import and retrieve import details

  4. Use the imports api to get detailed information for each certificate and private key imported related to the import id. For example:


    Example response

    HTTP 200 Created
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "status": "PROCESSING",
        "results": [
              "certificateBytes": [
              "fingerprint": "string",
              "status": "IMPORTED",
              "reason": "string"

What's next?

  • Learn more about Data Encryption Key (DEK).
  • Learn more about downloading a keystore.