Documentation Suite v25.1.1

Submit Search

POST Enrollment PFX

The POST /Enrollment 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)./PFX 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. method is used to enroll for a certificate by supplying data in the desired fields. This method returns HTTP 200 OK on a success with a message body containing a list of certificate details and any metadata 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. that was associated with the certificate request.

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

/certificates/enrollment/pfx/

Global or container-level schedule permissions for certificate stores are needed to install a certificate generated with this method into a certificate store (see the x-Certificate Format parameter A parameter or argument is a value that is passed into a function in an application.) using the POST /Enrollment/PFX/Deploy method (see POST Enrollment PFX Deploy) or POST /Enrollment/PFX/Replace method (see POST Enrollment PFX Replace).

Tip: Use the GET /Enrollment/PFX/Context/My method before this method to check which templates and CAs are available for enrollment for the requesting user before submitting the enrollment request.

Note: All enrollment (PFX, ODKG and CSR

A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA.), renewal, and revocation requests flow through Keyfactor Command 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. (see Workflow Definitions).

This method has two available versions. Keyfactor recommends using the newer method when possible. For more information about versioning, see Versioning.

Version 2

Version 1

Version 2 of the POST /Enrollment/PFX method redesigns how enrollment flow works to handle require approval functionality in a Keyfactor Command workflow with support for delivery into certificate stores. Users who are planning to use require approval workflow functionality and deliver enrolled certificates into certificate stores must use version 2 of this endpoint An endpoint is a URL that enables the API to gain access to resources on a server..

Note: The supported key algorithms for enrollment are determined based on:

System-wide enrollment pattern policy
Individual enrollment pattern policy
Supported algorithms set on the template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. at the CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. level

When configuring key information policies at the enrollment pattern level, only key sizes valid for the selected algorithm will be available. These are governed by the system-wide policy, enrollment pattern policy, and supported key sizes. For PFX enrollment and CSR generation, you must select a valid KeyType, and KeyLength or Curve as applicable, for the request.

Note: The PopulateMissingValuesFromAD parameter has been removed from the version 2 endpoint.

Table 458: POST Enrollment PFX v2 Input Parameters

Name In Description

Additional Enrollment Fields

Body

An object that provide values for any custom enrollment fields set on the enrollment pattern for the certificate template to supply custom request attributes to the CA during the enrollment process. The additionalPropx is the user-defined field name and the string is the value for the field. For example:

Copy

"AdditionalEnrollmentFields": {
   "CustomStringOne": "MyValue",
   "CustomMultiChoiceOne": "ValueTwo"
}

See Enrollment Pattern Operations for more information.

Certificate Authority

Body

Required^*. A string that sets the name of the certificate authority that will be used to enroll against if there is more than one available with the provided template or enrollment pattern. The certificate authority name can either be provided in hostname\\logical name format or as just the logical name. For example:

corpca01.keyexample.com\\CorpIssuingCA1 OR CorpIssuingCA1

If no certificate authority is provided, one will be chosen at random from the certificate authorities available for enrollment with the provided Template or EnrollmentPatternId.

Note: The list of CAs from which a CA is selected if a template or enrollment pattern is not supplied depends on the enrollment pattern's Restrict CAs setting (see Basic Information Tab) and the configuration tenant of the template associated with the enrollment pattern:

Restrict CAs Enabled: The CAs listed in the enrollment pattern’s Certificate Authorities list, limited to those in the same configuration tenant as the associated template.
Restrict CAs Disabled: All enterprise CAs defined in Keyfactor Command that share the same configuration tenant as the associated template.

In either case, the template associated with the enrollment pattern must also be available for enrollment on the CA and must have certificate request permissions granted to the appropriate user (see HTTPS CAs - Advanced Tab or DCOM CAs - Advanced Tab) in order for the CA to be included in the list.

This field is optional unless the enrollment is being done against a standalone CA, in which case it is required.

Chain Order

Body

A string indicating the order in which the certificate chain should be returned if IncludeChain is set to true. Supported values are:

EndEntityFirst
RootFirst

Curve

Body

A string indicating the elliptic curve for the requested key. ECC curves must be specified using the OID for the ECC algorithm. Keyfactor recommends using one of the most commonly used ECC curves when possible, if a specific alternate curve is not required. Common curves include:

P-256/ prime256v1/ secp256r1 - 1.2.840.10045.3.1.7
P-384/secp384r1 - 1.3.132.0.34
P-521/secp521r1 - 1.3.132.0.35

Show named curves and associated OIDs.

Name	OID
B-571	1.3.132.0.39
B-409	1.3.132.0.37
B-283	1.3.132.0.17
B-233	1.3.132.0.27
B-163	1.3.132.0.15
brainpoolP160r1	1.3.36.3.3.2.8.1.1.1
brainpoolP160t1	1.3.36.3.3.2.8.1.1.2
brainpoolP192r1	1.3.36.3.3.2.8.1.1.3
brainpoolP192t1	1.3.36.3.3.2.8.1.1.4
brainpoolP224r1	1.3.36.3.3.2.8.1.1.5
brainpoolP224t1	1.3.36.3.3.2.8.1.1.6
brainpoolP256r1	1.3.36.3.3.2.8.1.1.7
brainpoolP256t1	1.3.36.3.3.2.8.1.1.8
brainpoolP320r1	1.3.36.3.3.2.8.1.1.9
brainpoolP320t1	1.3.36.3.3.2.8.1.1.10
brainpoolP384r1	1.3.36.3.3.2.8.1.1.11
brainpoolP384t1	1.3.36.3.3.2.8.1.1.12
brainpoolP512r1	1.3.36.3.3.2.8.1.1.13
brainpoolP512t1	1.3.36.3.3.2.8.1.1.14
c2pnb163v1	1.2.840.10045.3.0.1
c2pnb163v2	1.2.840.10045.3.0.2
c2pnb163v3	1.2.840.10045.3.0.3
c2pnb176w1	1.2.840.10045.3.0.4
c2pnb208w1	1.2.840.10045.3.0.10
c2pnb272w1	1.2.840.10045.3.0.16
c2pnb304w1	1.2.840.10045.3.0.17
c2pnb368w1	1.2.840.10045.3.0.19
c2tnb191v1	1.2.840.10045.3.0.5
c2tnb191v2	1.2.840.10045.3.0.6
c2tnb191v3	1.2.840.10045.3.0.7
c2tnb239v1	1.2.840.10045.3.0.11
c2tnb239v2	1.2.840.10045.3.0.12
c2tnb239v3	1.2.840.10045.3.0.13
c2tnb359v1	1.2.840.10045.3.0.18
c2tnb431r1	1.2.840.10045.3.0.20
FRP256v1	1.2.250.1.223.101.256.1
K-571	1.3.132.0.38
K-409	1.3.132.0.36
K-283	1.3.132.0.16
K-233	1.3.132.0.26
K-163	1.3.132.0.1
P-521	1.3.132.0.35
P-384	1.3.132.0.34
P-256	1.2.840.10045.3.1.7
P-224	1.3.132.0.33
P-192	1.2.840.10045.3.1.1
prime192v1	1.2.840.10045.3.1.1
prime192v2	1.2.840.10045.3.1.2
prime192v3	1.2.840.10045.3.1.3
prime239v1	1.2.840.10045.3.1.4
prime239v2	1.2.840.10045.3.1.5
prime239v3	1.2.840.10045.3.1.6
prime256v1	1.2.840.10045.3.1.7
secp112r1	1.3.132.0.6
secp112r2	1.3.132.0.7
secp128r1	1.3.132.0.28
secp128r2	1.3.132.0.29
secp160k1	1.3.132.0.9
secp160r1	1.3.132.0.8
secp160r2	1.3.132.0.30
secp192k1	1.3.132.0.31
secp192r1	1.2.840.10045.3.1.1
secp224k1	1.3.132.0.32
secp224r1	1.3.132.0.33
secp256k1	1.3.132.0.10
secp256r1	1.2.840.10045.3.1.7
secp384r1	1.3.132.0.34
secp521r1	1.3.132.0.35
sect113r1	1.3.132.0.4
sect113r2	1.3.132.0.5
sect131r1	1.3.132.0.22
sect131r2	1.3.132.0.23
sect163k1	1.3.132.0.1
sect163r1	1.3.132.0.2
sect163r2	1.3.132.0.15
sect193r1	1.3.132.0.24
sect193r2	1.3.132.0.25
sect233k1	1.3.132.0.26
sect233r1	1.3.132.0.27
sect239k1	1.3.132.0.3
sect283k1	1.3.132.0.16
sect283r1	1.3.132.0.17
sect571r1	1.3.132.0.39
sm2p256v1	1.2.156.10197.1.301
wapip192v1	1.2.156.10197.1.301.101
ML-DSA-44	2.16.840.1.101.3.4.3.17
ML-DSA-65	2.16.840.1.101.3.4.3.18
ML-DSA-87	2.16.840.1.101.3.4.3.19

If this value is not supplied and the KeyType is ECC, the value will be derived from the KeyLength if the length provided matches one of the default curves (P-256, P-384, or P-521).

Custom Friendly Name

Body

Required^*. A string that sets a custom friendly name for the certificate.

This field is required if the Require Custom Friendly Name application setting is set to true (the default is false). See Application Settings: Enrollment Tab for more information.

Enrollment Pattern Id

Body

Required^*. An integer indicating the enrollment pattern to use when requesting the certificate. If this value is not provided, the default enrollment pattern defined for the template provided in the request (see the Template parameter) will be used.

One of either the Template or the EnrollmentPatternId is required unless the enrollment is being done against a standalone CA. If both the Template and EnrollmentPatternId are provided, the settings from the enrollment pattern take precedence. If both are specified, the enrollment will fail if the Template does not match the one defined by the specified enrollment pattern.

Include Chain

Body

A Boolean that sets whether to include the certificate chain in the response (true) or not (false). The default is true.

Note: In order for chain certificates to be included with end entity certificates for download, one of the following must be true:

All certificates in the chain must be in the Keyfactor Command database.
Each certificate in the chain must include an AIA (Authority Information Access) extension with an HTTP or HTTPS URL pointing to the issuer's certificate. These certificates must be accessible from the Keyfactor Command server. Only HTTP and HTTPS URLs are supported.
All certificates in the chain must be present in the Keyfactor Command server's local machine Trusted Root Certification Authorities and Intermediate Certification Authorities stores (Windows installations only).

Include Subject Header

Body

A Boolean that sets whether to include the subject header in the response (true) or not (false). The default is true if not included in the request. Only applicable when PEM format is selected. When set to false, the first line in the PEM file that contains the certificates subject information is removed. When set to true, the first line in the PEM file that contains the certificates subject information is included.

Works with Include Chain option where it will remove the subject header, when set to false, for each of the certificates returned in the chain. It also works with Include Private Key option enabled.

Install Into Existing Certificate Stores

Body

A Boolean that sets whether to deploy the certificate to certificate stores (true) or not (false). The default is true.

The RenewalCertificateId parameter is used in conjunction with InstallIntoExistingCertificateStores parameter to make the determination as to distribution of the certificate to certificate stores. If InstallIntoExistingCertificateStores is true, the certificate will be distributed to certificate stores that the certificate identified in RenewalCertificateId is found in.

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 are not allowed. To specify an Immediate enrollment, the JobTime should be omitted or left empty. 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.

Key Length

Body

A string indicating the key size for the requested key. Supported key sizes are:

255
256
384
448
521
2048
3072
4096
8192

The default varies depending on the selected KeyType. For RSA, the default is 2048.

KeyType

Body

A string indicating the algorithm for the request. Supported values are:

RSA
DSA
ECC
Ed448
Ed25519
ML-DSA-44
ML-DSA-65
ML-DSA-87

Metadata

Body

An object that set the values for the metadata fields that will be associated with the certificate once it is in Keyfactor Command. The additionalPropx is the field name and the string is the value for the field. For example:

Copy

"Metadata": {
   "AppOwnerFirstName": "William",  // This is a String field.
   "AppOwnerLastName": "Smith",
   "AppOwnerEmailAddress": "william.smith@keyexample.com",
   "BusinessCritical": "true",      // This is a Boolean field.
   "BusinessUnit": "E-Business",    // This is a Multiple Choice field with a pre-defined value.
   "Notes": "Here are some notes.", // This is a BigText field.
   "SiteCode": 3,                   // This is an integer field.
   "TicketResolutionDate": "2021-07-23"   // This is a Date field in yyyy-mm-dd format.
}

See Certificate Metadata for more information.

Microsoft Target CSP Body A string indicating the optional cryptographic service provider (CSP) to associate with the certificate in the Public Key Cryptography Standard #12 (PKCS #12) key provider name attribute (OID 1.3.6.1.4.1.311.17.1). A value should only be provided here if the Allow Cryptographic Service Providers (CSPs) application setting has been enabled and only values included in the Cryptographic Service Providers (CSPs) application setting list are valid for this value (see Application Settings: Enrollment Tab).

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. A certificate owner is required if the certificate template or system-wide settings Certificate Owner Role policy has been configured as Required.

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.

Password

Body

A string that sets the password to be used to encrypt the PKCS12 blob. If this is not supplied, a random password will be generated.

The minimum password length is controlled by the Password Length application setting. The default is 12. See Application Settings: Enrollment Tab for more information.

Renewal Certificate Id

Body

An integer that sets the ID of the certificate to be renewed when the method is called on a certificate renewal.

SANs

Body

An object that contains the elements for Keyfactor Command to use when generating the subject alternative name (SAN) for the certificate requested by the CSR, each of which is supplied as an array of strings. Show SAN key values.

Standard Value	Deprecated Value	Description
directory		Directory Name
dn		Distinguished Name
dns	dnsname, dns name	DNS Name
ediparty		EDI (Electronic Data Interchange) Party Name
email	mail	Email Address
guid		Globally Unique Identifier
ip	ip4, ipaddress	IP v4 Address Note: IP v4 and IP v6 addresses are handled separately in the Keyfactor Command Management Portal to allow for the application of separate regular expressions on enrollment, but they are stored using the standard ip value.
ip	ip6	IP v6 Address
oid		Object Identifier
other		Other Name
registered id		Registered ID (an OID)
upn		User Principal Name
uri		Uniform Resource Identifier
url		Uniform Resource Locator
x400		X400 Address
	rfc822	RFC 822 Name
	ms_ ntprincipal name	MS_ NTPrincipal Name (a string)
	ms_ ntds replication	MS_ NTDS Replication (a GUID)

For example:

Copy

"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip": [
      "192.168.2.73"
   ]
}

Stores

Body

An array of objects indicating the certificate stores to which the certificate should be distributed. Show store details.

Name	Description
Alias	A string containing the alias of the certificate upon entry into the store. The format of and requirement for this varies depending on the certificate store type and whether the Overwrite flag is selected. See PFX Enrollment for more information.
Overwrite	A Boolean that sets whether a certificate in the store with the Alias provided should be overwritten with the new certificate (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.
Properties	An object indicating the unique parameters defined for the certificate store type that need to be populated for the certificate. The key is the name of the specific parameter from the certificate store type definition as returned in the JobProperties on the store type using the GET CertificateStoreTypes method and the value is the value that should be set for that parameter on the certificate in the certificate store. For example, for NetScaler, the key name that is optionally used to associate the certificate with a virtual server is NetscalerVserver and is returned by GET CertificateStoreTypes like so: "JobProperties": [ "NetscalerVserver" ] It can be seen in the Keyfactor Command Management Portal when editing the certificate store type in the field for Management Job Custom Fields. The setting is referenced using the following format: Copy `"Properties": { "NetscalerVserver":"MyVirtualServerName" }` Note: The only built-in certificate store type that makes use of properties that can be set on a certificate-by-certificate basis in the store is NetScaler. You may have custom certificate store types that make use of this functionality.
StoreId	A string indicating the GUID of the certificate store to which the certificate should be deployed. Use the GET /CertificateStores method (see GET Certificate Stores) with a query of “Approved -eq true” to retrieve a list of all your approved certificate stores to determine the GUID(s) of the store(s).

Subject

Body

Required^*. A string containing the subject name using X.500 format. For example:

"Subject": "CN=websrvr14.keyexample.com,OU=IT,O=\"Key Example, Inc.\",L=Independence,ST=OH,C=US"

This field is required if the Common Name Regular Expression application setting is set to the default value of .+. See Application Settings: Enrollment Tab for more information.

Template

Body

Required^*. A string that sets the name of the certificate template that should be used to issue the certificate. The template short name should be used. See also EnrollmentPatternId.

Important: The template must be configured with at least one enrollment pattern in order to be used for enrollment (see POST Enrollment Patterns).

Note: This parameter is considered deprecated and may be removed in a future release.

Timestamp Body Required. A string indicating the current date and time. 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).

Use Legacy Encryption Body A Boolean that sets whether legacy encryption should be used in generating the PKCS#12 file resulting from the enrollment request (true) or not (false). Legacy encryption algorithms include PBE-SHA1-RC2-40 and PBE-SHA1-3DES. When legacy is not selected, encryption algorithms include AES-256-CBC, PBES2 with PBKDF2, and PBE-SHA1-3DES. The default is false.

x-Certificate Format

Header

Required. A string containing the desired output format for the certificate. Available options are:

JKS

Select the JKS option when you intend to create a Java keystore with the returned PKCS12Blob.
PEM

Select the PEM option when you intend to create a PEM file with the returned PKCS12Blob.
PFX

Select the PFX option when you intend to create a PKCS#12 (PFX/P12) file with the returned PKCS12Blob.
Replace

The Replace option is designed to be used when pushing an updated certificate to a certificate store (see POST Enrollment PFX Replace). Selecting this item causes data to be staged in preparation for the replace step.
Store

The Store option is designed to be used when pushing a newly obtained certificate to a certificate store (see POST Enrollment PFX Deploy). Selecting this item causes data to be staged in preparation for the deploy step.
Zip

Select the Zip option when you intend to output the returned PKCS12Blob as separate PEM-encoded certificate, private key, and optional chain certificate files wrapped together in a zip file.

Table 459: POST Enrollment PFX v2 Response Data

Value Description

Successful Stores An array of strings containing a comma delimited list of certificate stores, referenced by certificate store GUID, to which the certificate was successfully scheduled for deployment.

Certificate Information

An object containing information about the certificate that was requested. Show certificate information details.

Value	Description
Disposition Message	A string providing a message regarding the enrollment (e.g. The private key was successfully retained.).
Enrollment Context	An internally used Keyfactor Command field.
Issuer DN	A string indicating the issuer DN of the certificate.
Keyfactor ID	An integer indicating the Keyfactor Command reference ID of the issued certificate.
Keyfactor Request Id	An integer indicating the Keyfactor Command reference ID of the request.
Password	The random password generated to encrypt the PKCS12 blob if a password was not supplied in the request. If a password was supplied in the request, it is not returned in the response.
PKCS12 Blob	A string containing the base-64-encoded representation of the certificate in Zip or PFX format with the optional certificate chain. The string will need to be base-64 decoded for both Zip and PFX. This can be accomplished in a number of ways. For example, using PowerShell: Copy `$b64 = Get-Content 'C:\path\to\source\file' $targetFile = 'C:\path\to\target\file' $bytes = [Convert]::FromBase64String($b64)[IO.File]::WriteAllBytes($targetFile, $bytes)` Note: No value is returned for the PKCS12Blob if you select a certificate format of Store in the header. The Store option is designed to be used when pushing a newly obtained PFX certificate to a certificate store (see POST Enrollment PFX Deploy).
Request Disposition	A string indicating the state of the request (e.g. ISSUED).
Serial Number	A string indicating the serial number of the certificate.
Thumbprint	A string indicating the thumbprint of the certificate.
Workflow Instance Id	A string containing the Keyfactor Command reference GUID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.
Workflow Reference Id	An integer containing the Keyfactor Command reference ID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.

Metadata

An object containing the custom metadata values set on the certificate. The values vary depending on customization done in your environment. Show metadata structure details.

See Certificate Metadata for more information.

Version 1 of the POST /Enrollment/PFX method includes the same capabilities as version 2 except when used in conjunction with Keyfactor Command workflows that require approval with an intended end goal of delivering the resulting certificate into a certificate store. In this specific case, version 2 must be used.

Table 460: POST Enrollment PFX v1 Input Parameters

Additional Enrollment Fields

Name In Description

Additional Enrollment Fields

Body

An object that provide values for any custom enrollment fields set on the enrollment pattern for the certificate template to supply custom request attributes to the CA during the enrollment process. The additionalPropx is the used-defined field name and the string is the value for the field. For example:

Copy

"AdditionalEnrollmentFields": {
   "CustomStringOne": "MyValue",
   "CustomMultiChoiceOne": "ValueTwo"
}

See Enrollment Pattern Operations for more information.

Certificate Authority

Body

Required^*. A string that sets the name of the certificate authority that will be used to enroll against if there is more than one available with the provided template name. The certificate authority name can either be provided in hostname\\logical name format or as just the logical name. For example:

corpca01.keyexample.com\\CorpIssuingCA1 OR CorpIssuingCA1

If no certificate authority is provided, one will be chosen at random from the certificate authorities available for enrollment with the provided Template or EnrollmentPatternId.

Restrict CAs Enabled: The CAs listed in the enrollment pattern’s Certificate Authorities list, limited to those in the same configuration tenant as the associated template.
Restrict CAs Disabled: All enterprise CAs defined in Keyfactor Command that share the same configuration tenant as the associated template.

This field is optional unless the enrollment is being done against a standalone CA, in which case it is required.

ChainOrder

Body

A string indicating the order in which the certificate chain should be returned if IncludeChain is set to true. Supported values are:

EndEntityFirst
RootFirst

Curve

Body

A string indicating the elliptic curve for the requested key.

ECC curves may be specified using the well-known OIDs for ECC algorithms. Well-known OIDs include:

1.2.840.10045.3.1.7 = P-256/prime256v1/secp256r1
1.3.132.0.34 = P-384/secp384r1
1.3.132.0.35 = P-521/secp521r1

Custom Friendly Name

Body

Required^*. A string that sets a custom friendly name for the certificate.

This field is required if the Require Custom Friendly Name application setting is set to true (the default is false). See Application Settings: Enrollment Tab for more information.

Enrollment Pattern Id

Body

Include Chain

Body

A Boolean that sets whether to include the certificate chain in the response (true) or not (false). The default is true.

Include Subject Header

Body

Works with Include Chain option where it will remove the subject header, when set to false, for each of the certificates returned in the chain. It also works with Include Private Key option enabled.

Key Length

Body

A string indicating the key size for the requested key.

KeyType

Body

A string indicating the algorithm for the request. Supported values are:

RSA
DSA
ECC
Ed448
Ed25519
ML-DSA-44
ML-DSA-65
ML-DSA-87

Metadata

Body

Copy

"Metadata": {
   "AppOwnerFirstName": "William",  // This is a String field.
   "AppOwnerLastName": "Smith",
   "AppOwnerEmailAddress": "william.smith@keyexample.com",
   "BusinessCritical": "true",      // This is a Boolean field.
   "BusinessUnit": "E-Business",    // This is a Multiple Choice field with a pre-defined value.
   "Notes": "Here are some notes.", // This is a BigText field.
   "SiteCode": 3,                   // This is an integer field.
   "TicketResolutionDate": "2021-07-23"   // This is a Date field in yyyy-mm-dd format.
}

See Certificate Metadata for more information.

Owner Role Id

Body

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

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.

Password

Body

A string that sets the password to be used to encrypt the PKCS12 blob. If this is not supplied, a random password will be generated.

The minimum password length is controlled by the Password Length application setting. The default is 12. See Application Settings: Enrollment Tab for more information.

Populate Missing Values From AD

Body

A Boolean that sets whether to populate the information in the subject from Active Directory (true) or not (false). The default is false.

Renewal Certificate Id

Body

An integer that sets the ID of the certificate to be renewed when the method is called on a certificate renewal.

SANs

Body

Standard Value	Deprecated Value	Description
directory		Directory Name
dn		Distinguished Name
dns	dnsname, dns name	DNS Name
ediparty		EDI (Electronic Data Interchange) Party Name
email	mail	Email Address
guid		Globally Unique Identifier
ip	ip4, ipaddress	IP v4 Address Note: IP v4 and IP v6 addresses are handled separately in the Keyfactor Command Management Portal to allow for the application of separate regular expressions on enrollment, but they are stored using the standard ip value.
ip	ip6	IP v6 Address
oid		Object Identifier
other		Other Name
registered id		Registered ID (an OID)
upn		User Principal Name
uri		Uniform Resource Identifier
url		Uniform Resource Locator
x400		X400 Address
	rfc822	RFC 822 Name
	ms_ ntprincipal name	MS_ NTPrincipal Name (a string)
	ms_ ntds replication	MS_ NTDS Replication (a GUID)

For example:

Copy

"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip4": [
      "192.168.2.73"
   ]
}

Subject

Body

Required^*. A string containing the subject name using X.500 format. For example:

Copy

"Subject": "CN=websrvr14.keyexample.com,OU=IT,O=\"Key Example, Inc.\",L=Independence,ST=OH,C=US"

This field is required if the Common Name Regular Expression application setting is set to the default value of .+. See Application Settings: Enrollment Tab for more information.

Template

Body

Required^*. A string that sets the name of the certificate template that should be used to issue the certificate. The template short name should be used. See also EnrollmentPatternId.

Important: The template must be configured with at least one enrollment pattern in order to be used for enrollment (see POST Enrollment Patterns).

Note: This parameter is considered deprecated and may be removed in a future release.

Timestamp Body Required. A string indicating the current date and time. 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).

x-Certificate Format

Header

Required. A string containing the desired output format for the certificate. Available options are:

JKS

Select the JKS option when you intend to create a Java keystore with the returned PKCS12Blob.
PEM

Select the PEM option when you intend to create a PEM file with the returned PKCS12Blob.
PFX

Select the PFX option when you intend to create a PKCS#12 (PFX/P12) file with the returned PKCS12Blob.
Replace

The Replace option is designed to be used when pushing an updated certificate to a certificate store (see POST Enrollment PFX Replace). Selecting this item causes data to be staged in preparation for the replace step.
Store

The Store option is designed to be used when pushing a newly obtained certificate to a certificate store (see POST Enrollment PFX Deploy). Selecting this item causes data to be staged in preparation for the deploy step.
Zip

Select the Zip option when you intend to output the returned PKCS12Blob as separate PEM-encoded certificate, private key, and optional chain certificate files wrapped together in a zip file.

Table 461: POST Enrollment PFX v1 Response Data

Value Description

Certificate Information

An object containing information about the certificate that was requested. Show certificate information details.

Value	Description
Disposition Message	A string providing a message regarding the enrollment (e.g. The private key was successfully retained.).
Enrollment Context	An internally used Keyfactor Command field.
Issuer DN	A string indicating the issuer DN of the certificate.
Keyfactor ID	An integer indicating the Keyfactor Command reference ID of the issued certificate.
Keyfactor Request Id	An integer indicating the Keyfactor Command reference ID of the request.
Password	The random password generated to encrypt the PKCS12 blob if a password was not supplied in the request. If a password was supplied in the request, it is not returned in the response.
PKCS12 Blob	A string containing the base-64-encoded representation of the certificate in Zip or PFX format with the optional certificate chain. The string will need to be base-64 decoded for both Zip and PFX. This can be accomplished in a number of ways. For example, using PowerShell: Copy `$b64 = Get-Content 'C:\path\to\source\file' $targetFile = 'C:\path\to\target\file' $bytes = [Convert]::FromBase64String($b64)[IO.File]::WriteAllBytes($targetFile, $bytes)` Note: No value is returned for the PKCS12Blob if you select a certificate format of Store in the header. The Store option is designed to be used when pushing a newly obtained PFX certificate to a certificate store (see POST Enrollment PFX Deploy).
Request Disposition	A string indicating the state of the request (e.g. ISSUED).
Serial Number	A string indicating the serial number of the certificate.
Thumbprint	A string indicating the thumbprint of the certificate.
Workflow Instance Id	A string containing the Keyfactor Command reference GUID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.
Workflow Reference Id	An integer containing the Keyfactor Command reference ID of the workflow instance. Tip: Both the WorkflowInstanceId and the WorkflowReferenceId refer to the same workflow instance record—one using a GUID and one using a more human readable integer.

Metadata

An object containing the custom metadata values set on the certificate. The values vary depending on customization done in your environment. Show metadata structure details.

See Certificate Metadata 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 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: