POST Enrollment PFX Replace

The POST /EnrollmentClosed Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA)./PFXClosed A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers./Replace method is used to replace a certificate in a certificate store. It is intended to be used immediately after using the POST /Enrollment/PFX method to enroll for a PFX using the Replace value for the x-certificateformat header (see POST Enrollment PFX) or the POST /Enrollment/Renew method to renew a certificate already in a certificate store. This method returns HTTP 200 OK on a success with a message body containing the failed and succeeded stores.

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

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

Permissions for certificate stores can be set at either the global or certificate store container level. See Container Permissions for more information about global vs container permissions.

Note:  You could achieve the same end using the POST /Enrollment/PFX/Deploy method, but in that case you would need to provide the certificate store GUID(s), the alias of the current certificate in the certificate store(s), the certificate store type(s), and set the overwrite flag to true (as well as the certificate ID of the new certificate). To achieve a replacement with the POST /Enrollment/PFX/Replace method you only need to provide the certificate IDs of the certificate being replaced and the new certificate. All the rest of the work is done for you. The certificate will be replaced in all locations in which the certificate is found. If you want to replace the certificate in only some of the locations in which it is found, you will need to use the POST /Enrollment/PFX/Deploy method (see POST Enrollment PFX Deploy).
Tip:  The POST /Enrollment/PFX/Replace method must be used within 5 minutes of acquiring a certificate with the POST /Enrollment/PFX or POST /Enrollment/Renew method as the same user who executed the certificate request. After 5 minutes, the temporary staging data needed in order to deploy the certificate is automatically cleared and is no longer available for deployment.

Table 435: POST Enrollment PFX Replace Input Parameters

Name In Description
ExistingCertificateId Body

Required. The integer of the certificate that will be replaced that is already in the store(s). A management job will be created to replace the certificate in all stores in which it is found.

Use the GET /Certificates method to determine the certificate ID. This information is also available in the certificate details for a certificate in the Keyfactor Command Management Portal.
CertificateId Body

Required*. The integer for the certificate that needs to be deployed. This is returned in the response to the POST /Enrollment/PFX request.

Either the CertificateId or the RequestId is required but not both.
RequestId Body

Required*. The integer of the request ID for the certificate that needs to be deployed. This is returned in the response to the POST /Enrollment/PFX request.

Either the CertificateId or the RequestId is required but not both.
Password Body

Required*. A string with a password used to secure the certificate in the certificate store.

This field is required for store types that require an entry password, such as PEM stores.
JobTime Body

A string containing the date and time when the certificate should be deployed. 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). Dates in the past will cause a management job to be created to run immediately. Dates in the future will result in a management job set to run in the future. The default is to create a management job that runs immediately.

Table 436: POST Enrollment PFX Replace Response Data

Name Description
SuccessfulStores An array of strings containing the GUIDs for the certificates stores for which management jobs to deploy the certificate were successfully created.
Note:  Successful creation of a management job to deploy a certificate to a certificate store does not necessarily mean that a certificate will successfully be deployed to the store. A management job may fail for any number of reasons (e.g. permissions on the store). Use the GET /Certificates/{id} method with includeLocations=true to confirm that the certificate has successfully been deployed to the target store(s). The locations won't appear in the certificate record until after a certificate store inventory has been completed for each store.
FailedStores An array of strings containing the GUIDs for the certificates stores for which management jobs to deploy the certificate could not be created.
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.