2026/03/31 - AWS Certificate Manager - 1 new api methods
Changes Adds support for searching for ACM certificates using the new SearchCertificates API.
Retrieves a list of certificates matching search criteria. You can filter certificates by X.509 attributes and ACM specific properties like certificate status, type and renewal eligibility. This operation provides more flexible filtering than ListCertificates by supporting complex filter statements.
See also: AWS API Documentation
Request Syntax
client.search_certificates(
FilterStatement={
'And': [
{'... recursive ...'},
],
'Or': [
{'... recursive ...'},
],
'Not': {'... recursive ...'},
'Filter': {
'CertificateArn': 'string',
'X509AttributeFilter': {
'Subject': {
'CommonName': {
'Value': 'string',
'ComparisonOperator': 'CONTAINS'|'EQUALS'
}
},
'SubjectAlternativeName': {
'DnsName': {
'Value': 'string',
'ComparisonOperator': 'CONTAINS'|'EQUALS'
}
},
'ExtendedKeyUsage': 'TLS_WEB_SERVER_AUTHENTICATION'|'TLS_WEB_CLIENT_AUTHENTICATION'|'CODE_SIGNING'|'EMAIL_PROTECTION'|'TIME_STAMPING'|'OCSP_SIGNING'|'IPSEC_END_SYSTEM'|'IPSEC_TUNNEL'|'IPSEC_USER'|'ANY'|'NONE'|'CUSTOM',
'KeyUsage': 'DIGITAL_SIGNATURE'|'NON_REPUDIATION'|'KEY_ENCIPHERMENT'|'DATA_ENCIPHERMENT'|'KEY_AGREEMENT'|'CERTIFICATE_SIGNING'|'CRL_SIGNING'|'ENCIPHER_ONLY'|'DECIPHER_ONLY'|'ANY'|'CUSTOM',
'KeyAlgorithm': 'RSA_1024'|'RSA_2048'|'RSA_3072'|'RSA_4096'|'EC_prime256v1'|'EC_secp384r1'|'EC_secp521r1',
'SerialNumber': 'string',
'NotAfter': {
'Start': datetime(2015, 1, 1),
'End': datetime(2015, 1, 1)
},
'NotBefore': {
'Start': datetime(2015, 1, 1),
'End': datetime(2015, 1, 1)
}
},
'AcmCertificateMetadataFilter': {
'Status': 'PENDING_VALIDATION'|'ISSUED'|'INACTIVE'|'EXPIRED'|'VALIDATION_TIMED_OUT'|'REVOKED'|'FAILED',
'RenewalStatus': 'PENDING_AUTO_RENEWAL'|'PENDING_VALIDATION'|'SUCCESS'|'FAILED',
'Type': 'IMPORTED'|'AMAZON_ISSUED'|'PRIVATE',
'InUse': True|False,
'Exported': True|False,
'ExportOption': 'ENABLED'|'DISABLED',
'ManagedBy': 'CLOUDFRONT',
'ValidationMethod': 'EMAIL'|'DNS'|'HTTP'
}
}
},
MaxResults=123,
NextToken='string',
SortBy='CREATED_AT'|'NOT_AFTER'|'STATUS'|'RENEWAL_STATUS'|'EXPORTED'|'IN_USE'|'NOT_BEFORE'|'KEY_ALGORITHM'|'TYPE'|'CERTIFICATE_ARN'|'COMMON_NAME'|'REVOKED_AT'|'RENEWAL_ELIGIBILITY'|'ISSUED_AT'|'MANAGED_BY'|'EXPORT_OPTION'|'VALIDATION_METHOD'|'IMPORTED_AT',
SortOrder='ASCENDING'|'DESCENDING'
)
dict
A filter statement that defines the search criteria. You can combine multiple filters using AND, OR, and NOT logical operators to create complex queries.
And (list) --
A list of filter statements that must all be true.
(dict) --
A filter statement used to search for certificates. Can contain AND, OR, NOT logical operators or a single filter.
Or (list) --
A list of filter statements where at least one must be true.
(dict) --
A filter statement used to search for certificates. Can contain AND, OR, NOT logical operators or a single filter.
Not (dict) --
A filter statement that must not be true.
Filter (dict) --
A single certificate filter.
CertificateArn (string) --
Filter by certificate ARN.
X509AttributeFilter (dict) --
Filter by X.509 certificate attributes.
Subject (dict) --
Filter by certificate subject.
CommonName (dict) --
Filter by common name in the subject.
Value (string) -- [REQUIRED]
The value to match against.
ComparisonOperator (string) -- [REQUIRED]
The comparison operator to use.
SubjectAlternativeName (dict) --
Filter by subject alternative names.
DnsName (dict) --
Filter by DNS name in subject alternative names.
Value (string) -- [REQUIRED]
The DNS name value to match against.
ComparisonOperator (string) -- [REQUIRED]
The comparison operator to use.
ExtendedKeyUsage (string) --
Filter by extended key usage.
KeyUsage (string) --
Filter by key usage.
KeyAlgorithm (string) --
Filter by key algorithm.
SerialNumber (string) --
Filter by serial number.
NotAfter (dict) --
Filter by certificate expiration date. The start date is inclusive.
Start (datetime) --
The start of the time range. This value is inclusive.
End (datetime) --
The end of the time range. This value is inclusive.
NotBefore (dict) --
Filter by certificate validity start date. The start date is inclusive.
Start (datetime) --
The start of the time range. This value is inclusive.
End (datetime) --
The end of the time range. This value is inclusive.
AcmCertificateMetadataFilter (dict) --
Filter by ACM certificate metadata.
Status (string) --
Filter by certificate status.
RenewalStatus (string) --
Filter by certificate renewal status.
Type (string) --
Filter by certificate type.
InUse (boolean) --
Filter by whether the certificate is in use.
Exported (boolean) --
Filter by whether the certificate has been exported.
ExportOption (string) --
Filter by certificate export option.
ManagedBy (string) --
Filter by the entity that manages the certificate.
ValidationMethod (string) --
Filter by validation method.
integer
The maximum number of results to return in the response. Default is 100.
string
Use this parameter only when paginating results and only in a subsequent request after you receive a response with truncated results. Set it to the value of NextToken from the response you just received.
string
Specifies the field to sort results by. Valid values are CREATED_AT, NOT_AFTER, STATUS, RENEWAL_STATUS, EXPORTED, IN_USE, NOT_BEFORE, KEY_ALGORITHM, TYPE, CERTIFICATE_ARN, COMMON_NAME, REVOKED_AT, RENEWAL_ELIGIBILITY, ISSUED_AT, MANAGED_BY, EXPORT_OPTION, VALIDATION_METHOD, and IMPORTED_AT.
string
Specifies the order of sorted results. Valid values are ASCENDING or DESCENDING.
dict
Response Syntax
{
'Results': [
{
'CertificateArn': 'string',
'X509Attributes': {
'Issuer': {
'CommonName': 'string',
'DomainComponents': [
'string',
],
'Country': 'string',
'CustomAttributes': [
{
'ObjectIdentifier': 'string',
'Value': 'string'
},
],
'DistinguishedNameQualifier': 'string',
'GenerationQualifier': 'string',
'GivenName': 'string',
'Initials': 'string',
'Locality': 'string',
'Organization': 'string',
'OrganizationalUnit': 'string',
'Pseudonym': 'string',
'SerialNumber': 'string',
'State': 'string',
'Surname': 'string',
'Title': 'string'
},
'Subject': {
'CommonName': 'string',
'DomainComponents': [
'string',
],
'Country': 'string',
'CustomAttributes': [
{
'ObjectIdentifier': 'string',
'Value': 'string'
},
],
'DistinguishedNameQualifier': 'string',
'GenerationQualifier': 'string',
'GivenName': 'string',
'Initials': 'string',
'Locality': 'string',
'Organization': 'string',
'OrganizationalUnit': 'string',
'Pseudonym': 'string',
'SerialNumber': 'string',
'State': 'string',
'Surname': 'string',
'Title': 'string'
},
'SubjectAlternativeNames': [
{
'DirectoryName': {
'CommonName': 'string',
'DomainComponents': [
'string',
],
'Country': 'string',
'CustomAttributes': [
{
'ObjectIdentifier': 'string',
'Value': 'string'
},
],
'DistinguishedNameQualifier': 'string',
'GenerationQualifier': 'string',
'GivenName': 'string',
'Initials': 'string',
'Locality': 'string',
'Organization': 'string',
'OrganizationalUnit': 'string',
'Pseudonym': 'string',
'SerialNumber': 'string',
'State': 'string',
'Surname': 'string',
'Title': 'string'
},
'DnsName': 'string',
'IpAddress': 'string',
'OtherName': {
'ObjectIdentifier': 'string',
'Value': 'string'
},
'RegisteredId': 'string',
'Rfc822Name': 'string',
'UniformResourceIdentifier': 'string'
},
],
'ExtendedKeyUsages': [
'TLS_WEB_SERVER_AUTHENTICATION'|'TLS_WEB_CLIENT_AUTHENTICATION'|'CODE_SIGNING'|'EMAIL_PROTECTION'|'TIME_STAMPING'|'OCSP_SIGNING'|'IPSEC_END_SYSTEM'|'IPSEC_TUNNEL'|'IPSEC_USER'|'ANY'|'NONE'|'CUSTOM',
],
'KeyAlgorithm': 'RSA_1024'|'RSA_2048'|'RSA_3072'|'RSA_4096'|'EC_prime256v1'|'EC_secp384r1'|'EC_secp521r1',
'KeyUsages': [
'DIGITAL_SIGNATURE'|'NON_REPUDIATION'|'KEY_ENCIPHERMENT'|'DATA_ENCIPHERMENT'|'KEY_AGREEMENT'|'CERTIFICATE_SIGNING'|'CRL_SIGNING'|'ENCIPHER_ONLY'|'DECIPHER_ONLY'|'ANY'|'CUSTOM',
],
'SerialNumber': 'string',
'NotAfter': datetime(2015, 1, 1),
'NotBefore': datetime(2015, 1, 1)
},
'CertificateMetadata': {
'AcmCertificateMetadata': {
'CreatedAt': datetime(2015, 1, 1),
'Exported': True|False,
'ImportedAt': datetime(2015, 1, 1),
'InUse': True|False,
'IssuedAt': datetime(2015, 1, 1),
'RenewalEligibility': 'ELIGIBLE'|'INELIGIBLE',
'RevokedAt': datetime(2015, 1, 1),
'Status': 'PENDING_VALIDATION'|'ISSUED'|'INACTIVE'|'EXPIRED'|'VALIDATION_TIMED_OUT'|'REVOKED'|'FAILED',
'RenewalStatus': 'PENDING_AUTO_RENEWAL'|'PENDING_VALIDATION'|'SUCCESS'|'FAILED',
'Type': 'IMPORTED'|'AMAZON_ISSUED'|'PRIVATE',
'ExportOption': 'ENABLED'|'DISABLED',
'ManagedBy': 'CLOUDFRONT',
'ValidationMethod': 'EMAIL'|'DNS'|'HTTP'
}
}
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Results (list) --
A list of certificate search results containing certificate ARNs, X.509 attributes, and ACM metadata.
(dict) --
Contains information about a certificate returned by the SearchCertificates action. This structure includes the certificate ARN, X.509 attributes, and ACM metadata.
CertificateArn (string) --
The Amazon Resource Name (ARN) of the certificate.
X509Attributes (dict) --
X.509 certificate attributes such as subject, issuer, and validity period.
Issuer (dict) --
The distinguished name of the certificate issuer.
CommonName (string) --
The common name (CN) attribute.
DomainComponents (list) --
The domain component attributes.
(string) --
Country (string) --
The country (C) attribute.
CustomAttributes (list) --
A list of custom attributes in the distinguished name. Each custom attribute contains an object identifier (OID) and its corresponding value.
(dict) --
Defines the X.500 relative distinguished name (RDN).
ObjectIdentifier (string) --
Specifies the object identifier (OID) of the attribute type of the relative distinguished name (RDN).
Value (string) --
Specifies the attribute value of relative distinguished name (RDN).
DistinguishedNameQualifier (string) --
The distinguished name qualifier attribute.
GenerationQualifier (string) --
The generation qualifier attribute.
GivenName (string) --
The given name attribute.
Initials (string) --
The initials attribute.
Locality (string) --
The locality (L) attribute.
Organization (string) --
The organization (O) attribute.
OrganizationalUnit (string) --
The organizational unit (OU) attribute.
Pseudonym (string) --
The pseudonym attribute.
SerialNumber (string) --
The serial number attribute.
State (string) --
The state or province (ST) attribute.
Surname (string) --
The surname attribute.
Title (string) --
The title attribute.
Subject (dict) --
The distinguished name of the certificate subject.
CommonName (string) --
The common name (CN) attribute.
DomainComponents (list) --
The domain component attributes.
(string) --
Country (string) --
The country (C) attribute.
CustomAttributes (list) --
A list of custom attributes in the distinguished name. Each custom attribute contains an object identifier (OID) and its corresponding value.
(dict) --
Defines the X.500 relative distinguished name (RDN).
ObjectIdentifier (string) --
Specifies the object identifier (OID) of the attribute type of the relative distinguished name (RDN).
Value (string) --
Specifies the attribute value of relative distinguished name (RDN).
DistinguishedNameQualifier (string) --
The distinguished name qualifier attribute.
GenerationQualifier (string) --
The generation qualifier attribute.
GivenName (string) --
The given name attribute.
Initials (string) --
The initials attribute.
Locality (string) --
The locality (L) attribute.
Organization (string) --
The organization (O) attribute.
OrganizationalUnit (string) --
The organizational unit (OU) attribute.
Pseudonym (string) --
The pseudonym attribute.
SerialNumber (string) --
The serial number attribute.
State (string) --
The state or province (ST) attribute.
Surname (string) --
The surname attribute.
Title (string) --
The title attribute.
SubjectAlternativeNames (list) --
One or more domain names (subject alternative names) included in the certificate. This list contains the domain names that are bound to the public key that is contained in the certificate. The subject alternative names include the canonical domain name (CN) of the certificate and additional domain names that can be used to connect to the website.
(dict) --
Describes an ASN.1 X.400 GeneralName as defined in RFC 5280. Only one of the following naming options should be provided.
DirectoryName (dict) --
Contains information about the certificate subject. The Subject field in the certificate identifies the entity that owns or controls the public key in the certificate. The entity can be a user, computer, device, or service. The Subject must contain an X.500 distinguished name (DN). A DN is a sequence of relative distinguished names (RDNs). The RDNs are separated by commas in the certificate.
CommonName (string) --
The common name (CN) attribute.
DomainComponents (list) --
The domain component attributes.
(string) --
Country (string) --
The country (C) attribute.
CustomAttributes (list) --
A list of custom attributes in the distinguished name. Each custom attribute contains an object identifier (OID) and its corresponding value.
(dict) --
Defines the X.500 relative distinguished name (RDN).
ObjectIdentifier (string) --
Specifies the object identifier (OID) of the attribute type of the relative distinguished name (RDN).
Value (string) --
Specifies the attribute value of relative distinguished name (RDN).
DistinguishedNameQualifier (string) --
The distinguished name qualifier attribute.
GenerationQualifier (string) --
The generation qualifier attribute.
GivenName (string) --
The given name attribute.
Initials (string) --
The initials attribute.
Locality (string) --
The locality (L) attribute.
Organization (string) --
The organization (O) attribute.
OrganizationalUnit (string) --
The organizational unit (OU) attribute.
Pseudonym (string) --
The pseudonym attribute.
SerialNumber (string) --
The serial number attribute.
State (string) --
The state or province (ST) attribute.
Surname (string) --
The surname attribute.
Title (string) --
The title attribute.
DnsName (string) --
Represents GeneralName as a DNS name.
IpAddress (string) --
Represents GeneralName as an IPv4 or IPv6 address.
OtherName (dict) --
Represents GeneralName using an OtherName object.
ObjectIdentifier (string) --
Specifies an OID.
Value (string) --
Specifies an OID value.
RegisteredId (string) --
Represents GeneralName as an object identifier (OID).
Rfc822Name (string) --
Represents GeneralName as an RFC 822 email address.
UniformResourceIdentifier (string) --
Represents GeneralName as a URI.
ExtendedKeyUsages (list) --
Contains a list of Extended Key Usage X.509 v3 extension objects. Each object specifies a purpose for which the certificate public key can be used and consists of a name and an object identifier (OID).
(string) --
KeyAlgorithm (string) --
The algorithm that was used to generate the public-private key pair.
KeyUsages (list) --
A list of Key Usage X.509 v3 extension objects. Each object is a string value that identifies the purpose of the public key contained in the certificate. Possible extension values include DIGITAL_SIGNATURE, KEY_ENCHIPHERMENT, NON_REPUDIATION, and more.
(string) --
SerialNumber (string) --
The serial number assigned by the certificate authority.
NotAfter (datetime) --
The time after which the certificate is not valid.
NotBefore (datetime) --
The time before which the certificate is not valid.
CertificateMetadata (dict) --
ACM-specific metadata about the certificate.
AcmCertificateMetadata (dict) --
Metadata for an ACM certificate.
CreatedAt (datetime) --
The time at which the certificate was requested.
Exported (boolean) --
Indicates whether the certificate has been exported.
ImportedAt (datetime) --
The date and time when the certificate was imported. This value exists only when the certificate type is IMPORTED.
InUse (boolean) --
Indicates whether the certificate is currently in use by an Amazon Web Services service.
IssuedAt (datetime) --
The time at which the certificate was issued. This value exists only when the certificate type is AMAZON_ISSUED.
RenewalEligibility (string) --
Specifies whether the certificate is eligible for renewal. At this time, only exported private certificates can be renewed with the RenewCertificate command.
RevokedAt (datetime) --
The time at which the certificate was revoked. This value exists only when the certificate status is REVOKED.
Status (string) --
The status of the certificate.
A certificate enters status PENDING_VALIDATION upon being requested, unless it fails for any of the reasons given in the troubleshooting topic Certificate request fails. ACM makes repeated attempts to validate a certificate for 72 hours and then times out. If a certificate shows status FAILED or VALIDATION_TIMED_OUT, delete the request, correct the issue with DNS validation or Email validation, and try again. If validation succeeds, the certificate enters status ISSUED.
RenewalStatus (string) --
The renewal status of the certificate.
Type (string) --
The source of the certificate. For certificates provided by ACM, this value is AMAZON_ISSUED. For certificates that you imported with ImportCertificate, this value is IMPORTED. ACM does not provide managed renewal for imported certificates. For more information about the differences between certificates that you import and those that ACM provides, see Importing Certificates in the Certificate Manager User Guide.
ExportOption (string) --
Indicates whether the certificate can be exported.
ManagedBy (string) --
Identifies the Amazon Web Services service that manages the certificate issued by ACM.
ValidationMethod (string) --
Specifies the domain validation method.
NextToken (string) --
When the list is truncated, this value is present and contains the value to use for the NextToken parameter in a subsequent pagination request.