Documentation Suite v25.1.1

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)

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

Permissions for certificates and certificate stores can be set at either the global or certificate collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). and certificate store container level. You can use a mixture with, for example, global certificate permissions and container-level certificate store permissions. See Certificate Collection Permissions and Container Permissions for more information about global vs collection and container permissions.

Table 401: 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^*. 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 integer specifying an optional certificate collection identifier to validate that the user executing the request has sufficient permissions to do so. If a certificate collection ID is not supplied, the user must have global permissions to complete the action. Supplying a certificate collection ID allows for a check of the user's certificate collection-level permissions to determine whether the user has sufficient permissions at a collection level to complete the action. 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.1.1

On this page: