POST Certificates Import

The POST /Certificates/Import method is used to import a certificate provided in the request body into Keyfactor Command. This method returns HTTP 200 OK on a success with a message body containing information about the import.

Note:  Metadata - The import endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. does not check to determine if metadataClosed Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. needs to be updated. If the certificate exists in Keyfactor Command, the stored metadata will be replaced with whatever metadata was supplied in the import request, regardless of if the metadata has changed. Because of this, if the user does not have Metadata/Modify permissions, the resulting status will be one that indicates that metadata was not updated.
Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/certificates/import/
/Metadata/Modify (to update metadata)

Table 282: POST Certificates Import Input Parameters

Name In Description
Certificate Body

Required. A string containing the base-64 encoded contents of the certificate to be imported into Keyfactor Command. This may be a certificate with or without associated private key.

The following scenarios are accepted:

  • A base-64 encoded certificate without headers, footers and line feeds.

  • A base-64 encoded certificate with headers, footers and line feeds (in the case that the headers, footers and line feeds are not base-64 encoded).

  • A base-64 encoded certificate with headers, footers and line feeds that are in the base-64 encoding.

  • A base-64 ASCII (PEM) string.

With PowerShell, for example, you could use the following commands to convert certificates of various types to the appropriate format (referencing $b64Cert in the request body Certificate field).

  • PEM-encoded certificate:

    Copy 
    $crtCert = Get-Content 'C:\MyPath\MyCertificate.crt'
    $b64Cert = [System.Convert]::ToBase64String(
       [System.Text.Encoding]::ASCII.GetBytes($crtCert)
    )
    Note:  The commands are the same regardless of whether the PEM certificate file contains a private key. The private key is ignored. If the file contains chain certificates, the end entity certificate must precede the chain certificates; only the first certificate in the file is imported for this certificate type.

  • DER-encoded certificate:

    Copy 
    $derCert = Get-Content 'C:\MyPath\MyCertificate.der' -Encoding Byte
    $b64Cert = [System.Convert]::ToBase64String($derCert)

  • PKCS#12-encoded certificate:

    Copy 
    $pfxCert = Get-Content 'C:\MyPath\MyCertificate.pfx' -Encoding Byte
    $b64Cert = [System.Convert]::ToBase64String($pfxCert)
    Note:  Imports of this certificate type require specifying a Password to decrypt the specified file. Both the certificate and private key are imported.

  • PKCS#7-encoded binary certificate:

    Copy 
    $p7bCert = Get-Content 'C:\MyPath\MyCertificate.p7b' -Encoding Byte
    $b64Cert = [System.Convert]::ToBase64String($p7bCert)
    Note:  The order of the certificates in the certificate package is not important.
Tip:  You can use the POST /Certificates/Analyze method (see POST Certificates Analyze) to confirm that the string you have generated contains the contents that you expect.
Password Body Required*. A string containing the password used to decrypt the file containing the certificate to be imported. This field is required if a certificate of PKCS#12 format is provided in the Certificate field.
Metadata Body

An object containing the certificate metadata that will be associated with the certificate once it is imported. This is provided as a set of key value pairs with the metadata field name in the key and the value in the value. For example:

Copy 
"Metadata": {
   "AppOwnerFirstName": "John",
   "AppOwnerLastName": "Smith"
}
Store Ids Body An array of strings indicating the certificate store GUIDs that the imported certificate will be installed into.
Store Types Body An array of objects indicating the information for the specified store IDs. ClosedShow store type details.
Schedule Body A string containing the time the imported certificate should be scheduled to be installed into the certificate store. The date and time should be given using the ISO 8601 UTC time format YYYY-MM-DDTHH:mm:ss.000Z (e.g. 2023-11-19T16:23:01Z).
Owner Role Id Body

An integer indicating the Keyfactor Command reference ID of the security role assigned as the certificate owner.

Note:  To assign a certificate owner, one of OwnerRoleId or OwnerRoleName is required, not both.
Owner Role Name Body

A string containing the name of the security role assigned as the certificate owner. This name must match the existing name of the security role.

Note:  To assign a certificate owner, one of OwnerRoleId or OwnerRoleName is required, not both.

Table 283: POST Certificates Import Response Data

Name Description

Import Status

A string indicating the status of the import job indicating, for example, whether the certificate was newly created in Keyfactor Command or already existed in Keyfactor Command and was just updated based on provided private key, metadata, or location information. Possible values include:

  • AddCertUnknown
  • CreatedNew
  • CreatedNewWthKey
  • Exists
  • ExistsAddedKey
  • ExistsAddedKeyMissingOwnerRole
  • ExistsDidNotAddKey (Already exists with key)
  • ExistsDidNotAddKeyMissingOwnerRole
  • ExistsMissingOwnerRole
  • InsufficientEditMetadataPermission
  • InsufficientEditMetadataPermissionsMissingOwnerRole
  • InsufficientKeyPermission
  • NoRetentionPolicy
  • Unknown Template

 

Note:  InsufficientEditMetadataPermissionsMissingOwnerRole is not an error state. The certificate was imported but the user lacked Metadata/Modify permissions so the metadata was not changed and the OwnerRole was not updated either because of the following scenarios:

  • The certificate being imported already has a record in Keyfactor Command with an OwnerRole associated and the current user is not a member of theOwnerRole .

  • The import request did not specify an OwnerRole to save to the certificate.

Note:  Exists is not an error state. The certificate being imported already exists in Keyfactor Command , and the metadata associated with the certificate has been updated to the metadata supplied in the import request and the certificate's OwnerRole was set to the OwnerRole provided in the import request, if one was provided.
Invaild Key Stores An array of objects indicating which key store items failed with some information. ClosedShow key store details.
Job Status An integer indicating the state of all certificate store jobs.
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon () at the top of the Management Portal page next to the Log Out button.