Documentation Suite v25.3

Submit Search

POST Certificate Stores Certificates Add

The POST /CertificateStores/Certificates/Add method is used to add a certificate to one or more certificate stores. This method returns HTTP 200 OK on a success with an array of GUIDs for the add jobs. Use the GET /OrchestratorJobs/JobHistory method to check on the progress of the job after submission (see GET Orchestrator Jobs Job History).

Tip: The following permissions (see Security Roles and Claims) are required to use this feature:

/certificates/collections/read/

/certificate_stores/schedule/

/certificates/collections/read/#/ (where # is a reference to a specific certificate collection ID—see CollectionID, below)

/certificate_stores/schedule/#/ (where # is a reference to a specific certificate store container ID)

Permissions for certificates and certificate stores can be set at the system-wide level or with fine-grained control. You can mix these approaches—for example, applying system-wide certificate permissions alongside container-level permissions for certificate stores. See Certificate Collection Permissions and Container Permissions for more information about the differences between system-wide and more targeted permissions.

Table 437: POST Certificate Stores Certificates Add Input Parameters

Name In Description

CertificateId Body Required. An integer containing the Keyfactor Command reference ID of the certificate to be added to the certificate store(s).

Certificate Stores

Body

Required. An array of objects indicating the certificate store GUIDs to identify the certificate stores to which the certificate should be added and provide appropriate reference information for the certificate in the store. Show certificate store details.

Name Description

Certificate Store Ids Required. A string containing the GUID for the certificate store to which the certificate should be added.

Alias Required in some cases. A string providing an alias to be used for the certificate upon entry into the certificate store. The function of the alias varies depending on the certificate store type. For example, for an F5 device, it serves as the file name used to store the file in the device file system, minus the extension (e.g., use alias MyFile for a file named MyFile.pfx) while for a Java keystore, it is stored in the keystore associated with the certificate. Some certificate store types don't require an alias and some do. See Add Certificate for more information. This field may be required depending on the store type selected.

Job Fields An object that sets extra values for the job fields that will be associated with the add job. This option is typically used with custom Any Agent implementations.

Overwrite

A Boolean that sets whether a certificate in the store with the Alias provided should be overwritten with the certificate being added (true) or not (false). The default is false.

Use the GET /Certificates/Locations/{id} method (see GET Certificates Locations ID) to retrieve a list of the locations an existing certificate is in to determine the alias used for the certificate in the certificate store.

Entry Password

An object containing the password to set on the entry within the certificate store, if applicable. Only select certificate stores support entry passwords (e.g., Java keystores). See entry password details.

Name Description

Secret Value A string containing the password. This value only needs to be supplied if you're storing your password in the Keyfactor Command database.

Provider

An integer that identifies the PAM provider used to store the password. Use the GET /PamProviders method (see GET PAM Providers) to retrieve a list of your defined PAM providers to determine the PAM provider ID to use.

Parameters

An object containing the parameters required by your PAM provider, including the information that identifies the location of the password in the PAM solution. Use the GET /PamProviders method (see GET PAM Providers) to retrieve a list of the parameters used by your PAM provider. Only parameters where InstanceLevel is equal to true need to be supplied in the request.

For example, for Delinea (formerly Thycotic), this might be:

Copy

"EntryPassword": {
   "Provider": 2,
   "Parameters": {
      "SecretId": 5
   }
},

For CyberArk, this might be:

Copy

"EntryPassword": {
   "Provider": 5,
   "Parameters": {
      "Folder": "Root",
      "Object": "F5Password"
   }
},

Pfx Password A string that sets the password to use when saving a certificate with its private key in the certificate store. This is only relevant if there's a private key being added along with the certificate.

Include Private Key A Boolean that sets whether to include the private key of the certificate in the certificate store if private keys are optional for the given certificate store (true) or not (false). The default is false.

For example, to add to one IIS personal store and one NetScaler store without overwriting an existing certificate:

Copy

"CertificateStores": [
   {
      "Alias": "MyCertificate.pfx",
      "CertificateStoreId": "fde12aa7-6643-43db-88e8-5c91c5ce78b3",
      "IncludePrivateKey": true
   },
   {
      "Alias": "C2107973A928859C21330E566B299CD4A0705AE8",
      "CertificateStoreId": "322e12ea-43b2-4aab-80ae-c4ad4569b4e7",
      "IncludePrivateKey": true
   }
]

Schedule

Body

Required. An object indicating the inventory schedule for the add job. Show schedule details.

Name

Description

Off Turn off a previously configured schedule.

Immediate

A Boolean that indicates a job scheduled to run immediately (true) or not (false).

Tip: In some instances, jobs initially scheduled as Immediate will appear on a GET as null.

Exactly Once

A dictionary that indicates a job scheduled to run at the time specified with the parameter:

Name	Description
Time	The date and time to next run the job. 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).

For example, exactly once at 11:45 am:

Copy

"ExactlyOnce": {
   "Time": "2023-11-27T11:45:00Z"
}

Tip: In some instances, jobs initially scheduled as Immediate will appear on a GET as ExactlyOnce.

CollectionId

Body

An optional integer that specifies the certificate collection (CollectionId) to validate whether the user has sufficient permissions to perform the action. If a CollectionId is not provided, the user must have appropriate permissions granted system-wide or via certificate store containers.

Providing a CollectionId allows the system to check the user's permissions at the certificate collection level. Permissions are evaluated in the following order:

System-wide certificate permissions
Granular certificate permissions

Use either ContainerId or CollectionId, not both. If both are specified, CollectionId takes precedence, and the ContainerId is ignored (defaults to 0).

See Certificate Collection Permissions for more information.

Tip: See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor API

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 workflow

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.

Was this page helpful? Provide Feedback

Version v25.3

On this page: