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 Store 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 Overview) are required to use this feature:

CertificateStoreManagement: Schedule
CertificateEnrollment: EnrollPFX

Permissions for certificate stores can be set at either the global or certificate store container level. See Container Permissions in the Keyfactor Command Reference Guide 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 340: 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 PEMClosed A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. Usually, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key. stores.
JobTime Body

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. 2021-05-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 341: POST Enrollment PFX Replace Response Data

Name Description
SuccessfulStores An array of 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 GUIDs for the certificates stores for which management jobs to deploy the certificate could not be created.
Tip:  For code examples, see the Keyfactor API Endpoint Utility. To find the embedded web copy of this utility, click the help icon () at the top of the Keyfactor Command Management Portal page next to the Log Out button.