Importing private keys via API (PKCS12)

The imports endpoint lets you programmatically import private keys with their corresponding certificates into Next-Gen Trust Security (NGTS). This lets you import private keys and certificates so you can use the Push Provisioning feature for non-ASK certificates, and use NGTS as an enterprise vault for your machine identities.

note

Before attempting this import, ensure you have added your corresponding certificate chain to a trusted CA certificate. See Trusted CA Certificates in the NGTS product docs.

Before you begin

Knowledge of Data Encryption Key (DEK) encryption is a prerequisite for this API.

• Authenticate to the NGTS API. NGTS uses OAuth 2.0 machine accounts, not user API keys — see Getting started with the NGTS API to obtain a Bearer token.
• Note the following about the POST request body:
  • The value for pkcs12Keystore must be a base64 encoded file.
  • The values for encryptionKeyId and edgeInstanceId must be provided for the imports function to work.

note

PKCS #12 (also known as PKCS12 or PFX) is a binary format for storing a certificate chain and private key in a single, encryptable file that usually has the filename extension .p12 or .pfx.

Import certificates and their private keys

1. Retrieve the edgeInstanceId and encryptionKeyId values you'll need. Run the edgeinstances call and use the id from the edgeinstances object as the edgeInstanceId:

   GET https://api.strata.paloaltonetworks.com/ngts/v1/edgeinstances
   Authorization: Bearer <access_token>

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

   POST https://api.strata.paloaltonetworks.com/ngts/v1/certificates/imports
   Authorization: Bearer <access_token>

   Example request

   {
     "edgeInstanceId": "<your edgeInstanceId>",
     "encryptionKeyId": "<your encryptionKeyId>",
     "importInformation": [
       {
         "pkcs12Keystore": "<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 returns the job id, which you use to check the import status below.

   note

   There is a limit of 100 keys per API call. The API returns an error if you input more than 100 keys.

Check the status of the import

Use the imports API to get detailed information for each certificate and private key imported, using the import id:

GET https://api.strata.paloaltonetworks.com/ngts/v1/certificates/imports/3fa85f64-5717-4562-b3fc-2c963f66afa6
Authorization: Bearer <access_token>

Example response

HTTP 200 OK
{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "PROCESSING",
    "results": [
       {
          "certificateBytes": [
          "string"
          ],
          "serialNumber": "string",
          "status": "IMPORTED_CERTIFICATE_AND_PRIVATE_KEY",
          "reason": "string"
       }
    ]
}