Documentation Suite v25.1.1

Submit Search

GET Certificates

The GET /Certificates method is used to return a list of certificates with certificate details. Query parameters enable filtering using defined criteria, control over pagination by specifying the page number and return limit, and customization of sorting based on specified fields and order. This method returns HTTP 200 OK on a success with the requested certificates, as determined by filtering, and their certificate details.

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

/certificates/collections/read/

/certificates/collections/read/#/ (where # is a reference to a specific certificate collection ID)

Permissions for certificates 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). level. See Certificate Collection Permissions for more information about global vs collection permissions. See also the CollectionId input parameter A parameter or argument is a value that is passed into a function in an application., below.

Table 274: GET Certificates Input Parameters

Name	In	Description
includeRevoked	Query	A Boolean that sets whether to include revoked certificates in the results (true) or not (false). The default is false.
includeExpired	Query	A Boolean that sets whether to include expired certificates in the results (true) or not (false). The default is false.
includeLocations	Query	A Boolean that sets whether to include the Locations data in the response (true) or not (false). If false is selected, the LocationsCount and Locations fields will still appear in the response, but they will contain no data. The default is false.
includeMetadata	Query	A Boolean that sets whether to include the Metadata data in the response (true) or not (false). If false is selected, the Metadata field will still appear in the response, but it will contain no data. The default is false.
includeHasPrivateKey	Query	A Boolean that sets whether to include the correct value for HasPrivateKey in the response (true) or not (false). If false is selected, the HasPrivateKey field will appear in the response with a value of false regardless of whether the certificate actually has a stored private key or not. The default is false.
CollectionId	Query	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.
QueryString	Query	A string containing a query to limit the results (e.g. field1 -eq value1 AND field2 -gt value2). The default is to return all records. Fields available for querying through the API for the most part match those that appear in the Keyfactor Command Management Portal search dropdowns for the same feature. For querying guidelines, refer to: Certificate Search Page. The query fields supported for this endpoint are: AltKeySize AltKeyAlgorithm (an OID string) AltPublicKey AltSigningAlgorithm ArchivedKey CA CertId CertificateAuthorityId CertificateRenewed CertState CertStoreContainer CertStoreFQDN CertStorePath CN (alias: IssuedCN) DN (alias: IssuedDN) EKU EKUName ExpirationDate (alias: NotAfter) HasAltPrivateKey HasPrivateKey ImportDate IsHybridCertificate IssuedDate (aliases: NotBefore and EffectiveDate) IssuerDN KeyfactorRequestId KeyAlgorithm (an OID string) KeySize (alias: KeySizeInBits) KeyUsage NetBIOSPrincipal (alias: PrincipalName) NetBIOSRequester (alias: RequesterName) OU OwnerRoleName PublicKey RevocationDate (alias: RevocationEffDate) Revoker RFC2818Compliant SelfSigned SerialNumber SigningAlgorithm SSLDNSName SSLIPAddress (alias: SslHostName) SSLNetworkName SSLPort SAN TemplateDisplayName (alias: TemplateName) TemplateId TemplateShortName Thumbprint The following fields have been deprecated and may be removed in a future release; they will be honored if included in a request: AltKeyType (an integer) KeyType (an integer) The following fields have been deprecated and may be removed in a future release; they will be ignored if included in a request: CARequestID CertRequestId IsPfx RequestResolutionDate Note: Queries may be done using either the primary field name or the field alias(es).
PageReturned	Query	An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
ReturnLimit	Query	An integer that specifies how many results to return per page. The default is 50. Very large values can result in long processing time.
SortField	Query	A string containing the property by which the results should be sorted. Fields available for sorting through the API for the most part match those that appear as sortable columns in the Keyfactor Command Management Portal. The default sort field is Id.
SortAscending	Query	An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 275: GET Certificates Response Data

Name Description

AltKeySizeInBits An integer specifying the alternative key size in bits.

AltKeyType

An integer specifying the alternative key type of the certificate. Show key type details.

Value	Description
0	Unknown
1	RSA
2	DSA
3	ECC
5	Ed448
6	Ed25519
7	ML-DSA-44
8	ML-DSA-65
9	ML-DSA-87

AltKeyAlgorithm A string containing the OID in the format Friendly Name (OID).

AltKeyTypeString A string containing the alternative key type description (e.g. ML-DSA-44) as per the types and descriptions shown for AltKeyType.

AltSigningAlgorithm A string indicating the signing algorithm used by the CA to generate the alternative signature.

ArchivedKey A Boolean that indicates whether the certificate has a key archived in the issuing CA (true) or not (false).

CARecordId A string containing the CA's reference ID for certificate.

CARowIndex

An integer containing the CA's reference ID for certificate.

Note: The CARowIndex has been replaced by CARecordId, but will remain for backward compatibility. It will only contain a non-zero value for certificates issued by Microsoft CAs. For Microsoft CA certificates, the CARowIndex will be equal to the CARecordId value parsed to an integer.

CertificateAuthorityId An integer indicating the Keyfactor Command reference ID of the certificate authority that issued the certificate.

CertificateAuthorityName A string indicating the certificate authority that issued the certificate.

CertRequestId An integer containing the Keyfactor Command reference ID of the certificate request.

CertState

An integer specifying the state of the certificate. Show certificate state details.

Value	Name	Description
0	Unknown	This certificate entered the system in a manner other than a CA synchronization, so no status from a CA has been reported.
1	Active	The normal state for certificates brought in via CA synchronization. The certificate has not been revoked.
2	Revoked	The certificate has been revoked either within or outside Keyfactor Command.
6	Certificate Authority	The certificate synchronized in from a CA synchronization that is indicated to be that CA's own certificate. This state applies to Microsoft CAs only.
7	Parent Certificate Authority	The certificate synchronized in from a CA synchronzation that is indicated to be the certificate of a CA further up the chain. This state applies to Microsoft CAs only.

CertStateString

A string containing the certificate state. The possible values are (see descriptions under CertState):

Unknown (0)
Active (1)
Revoked (2)
Certificate Authority (6)
Parent Certificate Authority (7)

CertStoreTypeShortNames An array of comma-separated strings indicating the certificate stores types associated with each certificate.

ContentBytes A string containing the certificate as bytes.

CRLDistributionPoints

An array of objects containing the distribution points for the certificate revocation lists the certificate could be in. Show CRL distribution point details.

Name	Description
Id	An integer containing the Keyfactor Command reference ID of the CRL distribution point.
URL	A string indicating the URL of the CRL distribution point.
URLHash	A string indicating a hash of the URL.

Curve

A string indicating the OID of the elliptic curve algorithm configured for the certificate, for ECC templates. 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

DetailedKeyUsage

An object containing details of the key usage configured for the certificate. Show detailed key usage details.

Name	Description
CrlSign	A Boolean that indicates whether CRL signing is enabled for the certificate (true) or not (false).
DataEncipherment	A Boolean that indicates whether data encipherment (“Allow encryption of user data” in a Microsoft template) is enabled for the certificate (true) or not (false).
DecipherOnly	A Boolean that indicates whether the key of the certificate is intended for decipherment only (true) or not (false).
DigitalSignature	A Boolean that indicates whether digital signature is enabled for the certificate (true) or not (false).
EncipherOnly	A Boolean that indicates whether the key of the certificate is intended for encipherment only (true) or not (false).
KeyAgreement	A Boolean that indicates whether the certificate is configured for key agreement.
KeyCertSign	A Boolean that indicates whether the certificate is configured for certificate signing.
KeyEncipherment	A Boolean that indicates whether the certificate is configured for key encipherment.
NonRepudiation	A Boolean that indicates whether the certificate is configured for non-repudiation.
HexCode	A string containing the hexadecimal code representing the total key usage. For example, a value of a0 would indicate digital signature with key encipherment.

ExtendedKeyUsages

An array of objects containing the extended key usages associated with the certificate. Show Extended Key details.

Name	Description
Id	An integer containing the Keyfactor Command reference ID of the extended key usage.
Oid	A string indicating the OID of the extended key usage.
DisplayName	A string indicating the name of the extended key usage.

HasAltPrivateKey A Boolean that indicates whether the certificate has an alternative private key stored in Keyfactor Command (true) or not (false).

HasPrivateKey A Boolean that indicates whether the certificate has a private key stored in Keyfactor Command (true) or not (false).

Id An integer indicating the Keyfactor Command reference ID of the certificate.

ImportDate The date, in UTC, on which the certificate was imported into Keyfactor Command.

IssuedCN A string indicating the common name of the certificate.

IssuedDN A string indicating the distinguished name of the certificate.

IssuedEmail A string indicating the email address of the certificate.

IssuedOU A string indicating the organizational unit of the certificate.

IssuerDN A string indicating the distinguished name of the issuer.

KeyRecoverable A Boolean that indicates whether the certificate key is recoverable (true) or not (false).

KeySizeInBits An integer specifying the key size in bits.

KeyType

An integer specifying the key type of the certificate. Show key type details.

Value	Description
0	Unknown
1	RSA
2	DSA
3	ECC
5	Ed448
6	Ed25519
7	ML-DSA-44
8	ML-DSA-65
9	ML-DSA-87

KeyAlgorithm A string containing the OID in the format Friendly Name (OID).

KeyTypeString A string containing the key type description (e.g. RSA) as per the types and descriptions shown for KeyType.

KeyUsage

An integer indicating the total key usage of the certificate. Key usage is stored in Active Directory as a single value made of a combination of values. Show value details.

Value	Function	Description
0	None	No key usage parameters.
1	Encipherment Only	The key can be used for encryption only.
2	CRL Signing	The key can be used to sign a certificate revocation list (CRL).
4	Key Certificate Signing	The key can be used to sign certificates.
8	Key Agreement	The key can be used to determine key agreement, such as a key created using the Diffie-Hellman key agreement algorithm.
16	Data Encipherment	The key can be used for data encryption.
32	Key Encipherment	The key can be used for key encryption.
64	Nonrepudiation	The key can be used for authentication.
128	Digital Signature	The key can be used as a digital signature.
32768	Decipherment Only	The key can be used for decryption only.

For example, a value of 160 would represent a key usage of digital signature with key encipherment. A value of 224 would add nonrepudiation to those.

Locations

An array of objects containing the locations where the certificate is found using certificate store inventorying. Show certificate store location details.

Name

Description

StoreMachine

A string indicating the machine on which the certificate store is located.

StorePath

A string indicating the path on the machine where the certificate store is located. The format of this will vary depending on the type of store.

StoreType

An integer indicating the type of certificate store the certificate is located in. Show store types.

Value	Description
0	Java Keystore
2	PEM File
3	F5 SSL Profiles (deprecated)
4	IIS Roots (deprecated)
5	NetScaler (deprecated)
6	IIS Personal (deprecated)
7	F5 Web Server (deprecated)
8	IIS Revoked (deprecated)
9	F5 Web Server REST (deprecated)
10	F5 SSL Profiles REST (deprecated)
11	F5 CA Bundles REST (deprecated)
100	Amazon Web Services (deprecated)
101	File Transfer Protocol (deprecated)
1xx	User-defined certificate stores will be given a type ID over 101.

Alias

A string indicating the alias of the certificate in the certificate store.

ChainLevel

An integer stating how many certificates are below this certificate in the certificate chain stored at the given location.

CertStoreId

A string indicating the GUID of the certificate store.

LocationsCount

An array of objects containing a count of how many certificates are in each location type. This returns a list of type and count combination. For example:

Copy

"LocationsCount": [
   {
      "Type": "IIS",
      "Count": 2
   },
   {
      "Type": "F5-SL-REST",
      "Count": 1
   }
]

Metadata An object containing the metadata fields populated for the certificate.

NotAfter The date, in UTC, on which the certificate expires.

NotBefore The date, in UTC, on which the certificate was issued by the certificate authority.

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

OwnerRoleName A string containing the name of the security role assigned as the certificate owner of the certificate.

PrincipalId An integer indicating the Keyfactor Command reference ID of the principal (UPN) that requested the certificate. Typically, this field is only populated for end user certificates requested through Keyfactor Command. See also PrinicpalName.

PrincipalName A string containing the name of the principal (UPN) that requested the certificate. Typically, this field is only populated for end user certificates requested through Keyfactor Command.

RequesterId An integer indicating the Keyfactor Command reference ID of the identity that requested the certificate. See also RequesterName.

RequesterName A string containing the name of the identity that requested the certificate.

RevocationComment An internally used Keyfactor Command field.

RevocationEffDate The date, in UTC, on which the certificate was revoked, if applicable.

RevocationReason

An integer indicating the reason the certificate was revoked. Show revocation reason details.

Value	Description
0	Unspecified
1	Key Compromised
2	CA Compromised
3	Affiliation Changed
4	Superseded
5	Cessation Of Operation
6	Certificate Hold /Remove from Hold
999	Unknown

SerialNumber A string indicating the serial number of the certificate.

SigningAlgorithm A string indicating the signing algorithm used by the CA to generate the signature.

SSLLocations

An array of objects containing the locations where the certificate is found using SSL discovery. Show SSL location details.

Name	Description
StorePath	A string indicating the machine where the certificate was discovered.
AgentPool	A string indicating the GUID of the orchestrator pool that performed the SSL scan on the endpoint where the certificate was discovered.
IPAddress	A string indicating the IP address where the certificate was discovered.
Port	An integer indicating the port on which the certificate was discovered.
NetworkName	A string indicating the name of the SSL network that performed the SSL scan (discovery or monitoring) on the endpoint where the certificate was discovered.

SubjectAltNameElements

An array of objects containing the subject alternative name elements of the certificate. Show SAN details.

Name

Description

An integer containing the Keyfactor Command reference ID of the SAN Element.

Value

A string indicating the value of the SAN Element.

Type

An integer containing the type of SAN element. Show SAN type details.

Value	Description
0	Other Name
1	RFC 822 Name
2	DNS Name
3	X400 Address
4	Directory Name
5	Ediparty Name
6	Uniform Resource Identifier
7	IP Address
8	Registered Id
100	MS_NTPrincipalName
101	MS_NTDSReplication
999	Unknown

ValueHash

A string indicating a hash of the SAN value.

TemplateId An integer indicating the Keyfactor Command reference ID of the template associated with the certificate.

TemplateName A string indicating the display name of the template that was used when issuing the certificate.

Thumbprint A string indicating the thumbprint of the certificate.

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: