SSLMate CT Search APIv1

Certificate Transparency Search APIv1

Overview

When a publicly-trusted SSL certificate is issued, the event can be recorded in multiple Certificate Transparency logs in the form of a certificate, a precertificate, or both. SSLMate monitors public Certificate Transparency logs, coalescing all the certificate and precertificate entries for a particular issuance event into a single issuance object. SSLMate indexes the issuances by DNS name, and you can use the API described below to efficiently query all the unexpired issuances for a particular domain, and then poll for new issuances. Learn more

List Issuances for a Domain

Use this endpoint to list all unexpired certificate issuances for a domain.

First page: GET https://api.certspotter.com/v1/issuances?domain=DOMAIN

Subsequent pages: GET https://api.certspotter.com/v1/issuances?domain=DOMAIN&after=ID

The following parameters may be specified in the query string:

`domain`	Return issuances that are valid for the given DNS name, which must be a registered domain or subordinate to a registered domain. For example, `www.example.com` and `example.com` are valid, but `com` is not. DNS subject alternative names (SANs) and the subject common name (CN) are searched. This is the only mandatory parameter.
`include_subdomains`	If `true`, also return issuances that are valid for sub-domains (of any depth) of `domain`. Default: `false`.
`match_wildcards`	If `true`, also return issuances for wildcard DNS names that match `domain`. For example, a request for `domain=www.example.com&match_wildcards=true` will return issuances for `*.example.com`. Default: `false`.
`after`	Return issuances that were discovered by SSLMate after the issuance with the specified ID. If the `after` parameter is empty or omitted, the API will return the least-recently-discovered issuances for the domain. To retrieve more-recently-discovered issuances, take the `id` field of the last issuance and pass it to the `after` parameter of your next query. Repeat until an empty response is returned.
`expand`	Include the given field in the response, as described below. Repeat this parameter to expand multiple fields.

Response: JSON array of issuance objects, in the order that they were discovered by SSLMate.

Issuance Firehose

Use this endpoint to access a continuous stream of all certificate issuances as they are recorded in Certificate Transparency logs. Requires a subscription to Firehose Access.

First page: GET https://api.certspotter.com/v1/issuances/firehose

Subsequent pages: GET https://api.certspotter.com/v1/issuances/firehose?after=ID

The following parameters may be specified in the query string:

`after`	Return issuances that were discovered by SSLMate after the issuance with the specified ID. If the `after` parameter is empty or omitted, the API will return issuances have been discovered in approximately the last hour. To retrieve additional issuances, take the `id` field of the last issuance and pass it to the `after` parameter of your next query. Repeat until an empty response is returned.
`expand`	Include the given field in the response, as described below. Repeat this parameter to expand multiple fields.

after

Return issuances that were discovered by SSLMate after the issuance with the specified ID.

If the after parameter is empty or omitted, the API will return issuances have been discovered in approximately the last hour. To retrieve additional issuances, take the id field of the last issuance and pass it to the after parameter of your next query. Repeat until an empty response is returned.

expand Include the given field in the response, as described below. Repeat this parameter to expand multiple fields.

Response: JSON array of issuance objects, in the order that they were discovered by SSLMate.

The Firehose is intended for continuous consumption. After you reach an empty page, wait for the number of seconds indicated in the Retry-After header (currently 5 minutes) and repeat your query to get new issuances. If you wait longer than this, you may fall behind. If this happens, the API will return an error with the code lagging_client and you will need to restart monitoring from the end of the Firehose by omitting the after parameter from your next query. If you are receiving this error despite continuously consuming the Firehose, contact us for help.

Issuance Object

An issuance is represented by a JSON object with the following fields:

id string An opaque string which uniquely identifies this issuance object.

tbs_sha256 string The hex-encoded SHA-256 digest of the TBSCertificate, as defined in RFC 6962 Section 3.2. The tbs_sha256 uniquely identifies this issuance.

cert_sha256 string The hex-encoded SHA-256 digest (sometimes called fingerprint) of the certificate (if known) or precertificate (if certificate not known). The digest is computed over the ASN.1 DER encoding.

dns_names array of strings DNS names for which the certificate is valid, taken from both the DNS subject alternative names (SANs) and the subject common name (CN). Internationalized domain names are encoded in Punycode. Only present if expanded.

pubkey_sha256 string The hex-encoded SHA-256 digest of the DER-encoded Subject Public Key Info.

pubkey_der string The base64 representation of the DER-encoded Subject Public Key Info. Only present if expanded.

pubkey

object

Information about the certificate's public key. Only present if expanded.

The sub-object has the following fields:

`type`	string	`rsa`, `ecdsa`, or `unknown`. Additional key types may be defined in the future.
`bit_length`	integer	The bit length of the RSA modulus, typically 2048 or 4096. Present if `type` is `rsa`.
`curve`	string	The name of the elliptic curve: `P-256`, `P-384`, `P-521`, or `unknown`. Additional curve names may be defined in the future. Present if `type` is `ecdsa`.

issuer issuer object Information about the certificate authority which issued the certificate. Only present if expanded.

not_before string The "not before" time, in RFC 3339 format (e.g. 2016-06-16T00:00:00Z). This is ostensibly the time the certificate was issued, but certificate authorities can predate or postdate certificates (1-24 hours of predating is common), so be careful when relying on this value.

not_after string The "not after" (expiration) time, in RFC 3339 format (e.g. 2016-06-16T00:00:00Z).

revoked nullable bool Indicates if the certificate is revoked. In rare cases, this field is null if the revocation status is unknown.

revocation revocation object Additional details about the issuance's revocation status. Only present if expanded.

problem_reporting nullable string Instructions on how to request the certificate be revoked. In rare cases, this field is null if SSLMate does not have instructions. Only present if expanded.

cert_der string The base64 representation of the DER-encoded X.509 certificate (if known) or precertificate (if certificate is not known). Only present if expanded.

cert

object

Deprecated, use cert_der and cert_sha256 instead (click to show details)

Information about the certificate (if known) or precertificate (if certificate not known) corresponding to this issuance. Only present if expanded.

The sub-object has the following fields:

`type`	string	`cert` or `precert`. This field should generally be ignored. Do not treat certificates and precertificates differently unless you are sure you understand the security implications of doing so. Please contact us if you are unsure.
`sha256`	string	The hex-encoded SHA-256 digest of the DER-encoded X.509 (pre)certificate. Use `cert_sha256` from the issuance object instead.
`data`	string	The base64 representation of the DER-encoded X.509 (pre)certificate. Use `cert_der` from the issuance object instead.

Issuer Object

A certificate issuer is represented by a JSON object with the following fields:

friendly_name string The organization which issued the certificate. This name is curated by SSLMate to be an accurate and helpful way to identify the issuer of a certificate, so we recommend you use it instead of the certificate's Issuer Distinguished Name, which is often misleading, incorrect, or unhelpful. Note that friendly_name is intended for human consumption, and may change over time due to rebranding, mergers, or acquisitions; if you need a long-term identifier to programmatically compare against a list of authorized issuers, use caa_domains instead.

website nullable string The URL of the issuer's website, or null if unknown. Only present if expanded.

caa_domains nullable array of strings The domain names which can be placed in a CAA record to authorize the issuer. In rare cases, this field is null if SSLMate does not know this information. You can compare this field against the CAA records for your domain to determine if a certificate is authorized: at least one of the values in caa_domains should be in your domain's CAA record set. Only present if expanded.

operator

nullable object

Information about the organization which controls the issuer's private key. In rare cases, this field is null if SSLMate does not know who controls the private key. Operator information is typically only useful to WebPKI security researchers. Only present if expanded.

The sub-object has the following fields:

`name`	string	The name of the organization.
`website`	nullable string	The URL of the organization's website, or `null` if unknown.

pubkey_sha256 string The hex-encoded SHA-256 digest of the issuer's DER-encoded Subject Public Key Info.

pubkey_der string The base64 representation of the issuer's DER-encoded Subject Public Key Info. Only present if expanded.

name string The distinguished name of the issuer, formatted according to RFC 2253. This field is controlled by the certificate authority and often contains misleading, incorrect, or unhelpful information, so you should use friendly_name instead unless you are concerned with PKI minutiae.

name_der string The base64 representation of the issuer's DER-encoded distinguished name. This field is only useful if you are concerned with PKI minutiae. Only present if expanded.

Revocation Object

Revocation details are contained in a JSON object with the following fields:

`time`	nullable string	The time of the revocation, in RFC 3339 format. `null` if the certificate is not revoked or if the revocation status is unknown.
`reason`	nullable integer	The RFC 5280 reason code explaining why the certificate was revoked. See Mozilla's Revocation Reasons documentation for information about the meaning of each reason code. Be aware that certificate authorities do not always provide an accurate reason so the utility of this field may be limited. This field is `null` if the certificate is not revoked or if the revocation status is unknown.
`checked_at`	nullable string	The time at which SSLMate checked the certificate's revocation status, in RFC 3339 format. `null` if the revocation status is unknown.

Revocation status is unknown in the following cases:

The certificate is expired. Expired certificates are not trusted anyways, so revocation is inapplicable.
The certificate is so malformed that its revocation status can't be checked. Most certificate consumers will reject the certificate.
The certificate issuer doesn't publish valid certificate revocation lists (CRLs). Note that all SSL certificate authorities trusted by Mozilla and Apple are required to publish valid CRLs. SSLMate monitors CAs for compliance with this requirement and reports non-compliant CAs, so this case should be rare.

Example Issuance (with all non-deprecated fields expanded)

{
	"id":"4326219514",
	"tbs_sha256":"db7c55f74732269c45fda91264003b2a25adc7ff2df687252f60772850449926",
	"cert_sha256":"20cbc0d1e87ed1d71d3b84533667ef60f22fffee634108711376dec87a38d4e2",
	"dns_names":["certs.sandbox.sslmate.com","certs.sslmate.com","sandbox.sslmate.com","sslmate.com","www.sslmate.com"],
	"pubkey_sha256":"1b1cebcd061ba39746a477db7b90d6871d648bd293ef50e053a6c54c5c3ac112",
	"pubkey_der":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA235/3Y/E4yPAHPa37C7Fgp7KPVjjuTB5vKV9nYIJzfp7NgvDBlf7k5bZFCSsSIj2txhL0hzXBwvmy7u7CYR7CApr2Rx2UPOl7Gmlt/DmtfyKac8Iunn2ozuGZDtxq19Go4NL9jl9e9O3H/lcL/ZFqzbUNlKIOfkOYkOxM3qpQXHTXuhkeI2MJO/S4wX8y8/8uhArWQ9eh/YrtJlO9fla60kLUlQF7mtJTc+0oB3+N4eF5t2a8Pav00T6lVvH8hMhbY0nZ/tBCD6/I6yelh8cP094VRJEGWs+zcEuXpz4FsZggkhF/l+AhQ+DfgxZhno4M60kBKC8Un1BTGX5TjfjJQIDAQAB",
	"pubkey":{"type":"rsa","bit_length":2048},
	"issuer":{
		"friendly_name":"Sectigo",
		"website":"https://sectigo.com/",
		"caa_domains":["sectigo.com","comodo.com","comodoca.com","usertrust.com","trust-provider.com"],
		"operator":{"name":"Sectigo","website":"https://sectigo.com/"},
		"pubkey_sha256":"e1ae9c3de848ece1ba72e0d991ae4d0d9ec547c6bad1dddab9d6beb0a7e0e0d8",
		"pubkey_der":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1nMz1tc8INAA0hdFuNY+B6I/x0HuMjDJsGz99J/LEpgPLT+NTQEMgg8Xf2Iu6bhIefsWg06t1zIlk7cHv7lQP6lMw0Aq6Tn/2YHKHxYyQdqAJrkjeocgHuP/IJo8lURvh3UGkEC0MpMWCRAIIz7S3YcPb11RFGoKacVPAXJpz9OTTG0EoKMbgn6xmrntxZ7FN3ifmgg0+1YuWMQJDgZkW7w33PGfKGioVrCSo1yfu4iYCBskHaswha6vsC6eep3BwEIc4gLw6uBK0u+QDrTBQBbwb4VCSmT3pDCg/r8uoydajotYuK3DGReEY+1vVv2Dy2A0xHS+5p3b4eTlygxfFQIDAQAB",
		"name":"C=GB, ST=Greater Manchester, L=Salford, O=Sectigo Limited, CN=Sectigo RSA Domain Validation Secure Server CA",
		"name_der":"MIGPMQswCQYDVQQGEwJHQjEbMBkGA1UECBMSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYDVQQHEwdTYWxmb3JkMRgwFgYDVQQKEw9TZWN0aWdvIExpbWl0ZWQxNzA1BgNVBAMTLlNlY3RpZ28gUlNBIERvbWFpbiBWYWxpZGF0aW9uIFNlY3VyZSBTZXJ2ZXIgQ0E="
	},
	"not_before":"2022-10-22T00:00:00Z",
	"not_after":"2023-11-21T23:59:59Z",
	"revoked":false,
	"revocation":{"time":null,"reason":null,"checked_at":"2022-12-19T18:47:39Z"},
	"problem_reporting":"To revoke one or more certificates issued by Sectigo for which you (i) are the Subscriber or (ii) control the domain or (iii) have in your possession the private key, you may use our automated Revocation Portal here:\u000A  ?? https://secure.sectigo.com/products/RevocationPortal\u000A\u000ATo programatically revoke one or more certificates issued by Sectigo for which you have in your possession the private key, you may use the ACME revokeCert method at this endpoint:\u000A  ?? ACME Directory: https://acme.sectigo.com/v2/keyCompromise\u000A  ?? revokeCert API: https://acme.sectigo.com/v2/keyCompromise/revokeCert\u000A\u000ATo report any other abuse, fraudulent, or malicious use of Certificates issued by Sectigo, please send email to:\u000A  ?? For Code Signing Certificates: signedmalwarealert[at]sectigo[dot]com\u000A  ?? For Other Certificates (SSL/TLS, S/MIME, etc): sslabuse[at]sectigo[dot]com",
	"cert_der":"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"
}

Expanding Object Fields

As indicated in the documentation for an object, certain object fields are not included in responses by default. To include such a field, you must specify the field name in the request's expand parameter. This parameter can be specified more than once to expand multiple fields.

To expand a field that is nested in another field, specify the parent field name, a dot (.), and the child field name. For example, specify issuer.caa_domains to expand the caa_domains field of the issuer field.

Example: GET https://api.certspotter.com/v1/issuances?domain=example.com&expand=dns_names&expand=issuer&expand=issuer.caa_domains

Issuance Pagination

The API returns a limited number of issuances in a single response. To retrieve additional issuances, take the id field of the last issuance and pass it to the issuances endpoint in the after parameter (leaving the other parameters as-is). Repeat until the issuances endpoint returns an empty array.

Polling For New Issuances

When the issuances endpoint returns an empty array, it includes a Retry-After HTTP header containing a number of seconds. After the specified time has elapsed, you may retry the request. If SSLMate has discovered new issuances matching your query, they will be returned. You can then request subsequent pages until another empty response is returned.

Authentication

You can make a limited number of unauthenticated API queries per hour, for personal or evaluation purposes.

When you're ready to launch in production, we ask that you sign up for an account and authenticate to the API using one the following methods:

Specify an API key in the Authorization header as a Bearer Token.
Specify an API key as the username using HTTP Basic Authentication. Use an empty password.

Examples:

curl -H "Authorization: Bearer 123_sampleapikey" https://api.certspotter.com/v1/issuances?domain=example.com

curl -u 123_sampleapikey: https://api.certspotter.com/v1/issuances?domain=example.com

Errors

When the API cannot complete a request due to a client-caused error, it returns an HTTP status code in the range 400 to 499, inclusive. For server-caused errors, the HTTP status code is in the range 500 to 599, inclusive. The response body contains a JSON object, called an error object, with the following fields:

`code`	string	A short machine-readable code that describes the error. The meaning of an error code will never change, although additional error codes may be defined in the future. See below for the currently-defined error codes.
`message`	string	A human-readable message. The value of this field is only suitable for human consumption; the exact wording of messages may change without notice. For a machine-readable code, use the code field.
`field`	string	The name of the request field that caused the error. Only present if the error is field-specific.
`sub_errors`	array	An array of error objects that describe the problem(s) which caused this error in greater detail. Only present for some error types. Sub-errors do not have further sub-errors.

The following error codes are defined:

`bad_request`	Client did not follow the API - see `message` for details
`bad_query`	One or more fields in the query string is invalid - see `sub_errors` for details
`missing_field`	The indicated field is required but was not provided by the client
`invalid_value`	The indicated field contains an invalid value - see `message` for details
`out_of_range`	The indicated field contains a value that is not within the allowed range
`lagging_client`	Client is not consuming the firehose quickly enough
`bad_credentials`	Client provided invalid API key
`payment_required`	Your subscription has been suspended for non-payment; visit https://sslmate.com/account/subscriptions to renew your subscription
`unauthorized`	Provided API key is not authorized to perform action; visit https://sslmate.com/account/api_keys to create a new API key
`disabled_credentials`	Provided API key has been disabled; visit https://sslmate.com/account/api_keys to re-enable the API key
`not_allowed_by_plan`	Your subscription does not support this feature; visit https://sslmate.com/account/ct_search_api to upgrade
`method_not_allowed`	Client used an HTTP method that is not allowed for this action
`rate_limited`	Client request rate has exceeded what your subscription allows; visit https://sslmate.com/account/ct_search_api to get a higher rate limit
`internal_error`	A server-caused error; these errors are rare and are automatically investigated by SSLMate; you may retry your request with exponential backoff
`service_outage`	The API is temporarily unavailable
`timeout`	The search query exceeded the time limit of your subscription; visit https://sslmate.com/account/ct_search_api to get a longer timeout

Provisioned Indexes

Provisioned indexes speed up full-domain queries of domains which have a large number of certificates. Provisioned indexes start at $100/month per domain. Contact us to set up a provisioned index.

Compatibility

SSLMate may make backwards-compatible changes to this API, such as adding new fields to responses, changing the order of response fields, changing the whitespace between JSON tokens, or adding new optional parameters to requests. Some parts of the API have additional compatibility considerations documented above - for example, it is noted under the documentation for the pubkey.type field that additional public key types may be defined in the future.

Backwards-incompatible changes will be avoided if at all possible, but should such a change become necessary, SSLMate will provide at least 24 months notice except in rare cases where security or stability is at risk if the change is not made. To ensure you receive notice, please use your API key when making requests.

SSLMate may discontinue, alter, or restrict functionality for free tier users at any time without notice.

Certificate Transparency Search APIv1

Overview

List Issuances for a Domain

Issuance Firehose

Issuance Object

Issuer Object

Revocation Object

Example Issuance (with all non-deprecated fields expanded)

Expanding Object Fields

Issuance Pagination

Polling For New Issuances

Authentication

Errors

Provisioned Indexes

Compatibility

See Also