Cert Spotter

Overview

When a publicly-trusted certificate is issued, it can result in a certificate, a pre-certificate, or both being logged to multiple Certificate Transparency logs. Cert Spotter monitors public Certificate Transparency logs, coalescing all the certificates and pre-certificates for a particular issuance event into a single issuance object. Cert Spotter indexes the issuances by DNS name, allowing you to efficiently query all the issuances for a particular domain, and then poll for new issuances.

Issuance Object

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

`id`	string	An opaque identifier which represents this issuance object.
`tbs_sha256`	string	The hex-encoded SHA-256 digest of the TBSCertificate, as defined in RFC 6962 Section 3.2.
`dns_names`	array of strings	DNS names for which the issuance is valid, taken from both the Subject CN and the DNS SANs. Internationalized domain names are encoded in Punycode. Only present if expanded.
`pubkey_sha256`	string	The hex-encoded SHA-256 digest of the Subject Public Key Info.
`issuer`	issuer object	Information about the issuer. Only present if expanded.
`not_before`	string	The not before date, in RFC 3339 format (e.g. `2016-06-16T00:00:00-00:00`).
`not_after`	string	The not after (expiration) date, in RFC 3339 format (e.g. `2016-06-16T00:00:00-00:00`).
`cert`	certificate object	The certificate (if known) or pre-certificate (if certificate not known) corresponding to this issuance. Only present if expanded.

Certificate Object

A certificate or pre-certificate is represented by a JSON object with the following fields:

`id`	string	An opaque identifier which represents this certificate object.
`type`	string	`cert` or `precert`.
`sha256`	string	The hex-encoded SHA-256 digest of the X.509 (pre-)certificate, encoded in ASN.1 DER.
`data`	string	The base64 representation of the X.509 (pre-)certificate, encoded in ASN.1 DER.

Issuer Object

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

`name`	string	The subject distinguished name of the issuer, formatted according to RFC 2253.
`pubkey_sha256`	string	The hex-encoded SHA-256 digest of the issuer's Subject Public Key Info.

Example Issuance (with all fields expanded)

{
	"id":"23527804",
	"tbs_sha256":"e94af5279c0b9253bcefca8e65b9e0de5cb3be25855c73bccdcff81701b8a2e6",
	"dns_names":["*.example.com","example.com"],
	"pubkey_sha256":"9bc7338cde39136a1fcfda35887cec3b278d2e72f6e360ca791a544321aeedef",
	"issuer":{"name":"C=US, O=\"thawte, Inc.\", CN=thawte SSL CA - G2","pubkey_sha256":"691e8352a37ca8ae07406841a5c0cb56791102f3871f56de8694145355e5edf1"},
	"not_before":"2016-07-14T00:00:00-00:00",
	"not_after":"2018-07-14T23:59:59-00:00",
	"cert":{"id":"24173516","type":"precert","sha256":"94482136a1400bc3a1136feca3e79d4d200e03dd20b245d19f0e78b5679eaf48","data":"MIIEzjCCA7agAwIBAgIQEobGqV5B2WhzJt1o7kIUFjANBgkqhkiG9w0BAQsFADBBMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMdGhhd3RlLCBJbmMuMRswGQYDVQQDExJ0aGF3dGUgU1NMIENBIC0gRzIwHhcNMTYwNzE0MDAwMDAwWhcNMTgwNzE0MjM1OTU5WjBwMQswCQYDVQQGEwJLUjEOMAwGA1UECAwFU2VvdWwxEjAQBgNVBAcMCVNlb2Noby1ndTESMBAGA1UECgwJQ3Jvc3NjZXJ0MREwDwYDVQQLDAhWQ1MgdGVzdDEWMBQGA1UEAwwNKi5leGFtcGxlLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMFDRD/iURNGYWDu1A4aQKMP5X/QbehylISxE0aF4mzNfT0xdl1owpxotOPSP8wqy77WNuHXIckYS/4SxNX9f3aJ/5cBFQIqRvJzyB7Mv48EtTk00w5/1b53xFpqptJFkandcN4dIZHRfMGR9l1+mj4tTxEaSuEGl7z4Rdvq2L3Q0YeMdNScqLQ0MbS5khmPHP+eZM8wajtZ5HE7/TjDOU+0pNmnwyrUBNIZ9PpC0oJmzSSEjEF8qyQZc7VIqkjAPVLlyw/vf1j/1rPOGkfV0wAQoMkFSSQtOVuxT7+nakhv8kS0O/8fTtQ7MWRusq8fWaX8fpBgEPI6XNRJzC04scsCAwEAAaOCAZEwggGNMCUGA1UdEQQeMByCDSouZXhhbXBsZS5jb22CC2V4YW1wbGUuY29tMAkGA1UdEwQCMAAwbgYDVR0gBGcwZTBjBgZngQwBAgIwWTAmBggrBgEFBQcCARYaaHR0cHM6Ly93d3cudGhhd3RlLmNvbS9jcHMwLwYIKwYBBQUHAgIwIwwhaHR0cHM6Ly93d3cudGhhd3RlLmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIFoDAfBgNVHSMEGDAWgBTCT0hX/NFPmsBdOH0OBdvZLrVSYDArBgNVHR8EJDAiMCCgHqAchhpodHRwOi8vdGouc3ltY2IuY29tL3RqLmNybDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwVwYIKwYBBQUHAQEESzBJMB8GCCsGAQUFBzABhhNodHRwOi8vdGouc3ltY2QuY29tMCYGCCsGAQUFBzAChhpodHRwOi8vdGouc3ltY2IuY29tL3RqLmNydDATBgorBgEEAdZ5AgQDAQH/BAIFADANBgkqhkiG9w0BAQsFAAOCAQEAWr/m0cGFDRcuKcvpH/tWXDIpwWZGgE0AhaZQtAcU1O5X8j1k48kibWagjfLo84aUjiQyEhFN8O15t/B4QI9KlvtRCKbkKB/EUgzDK4wMUlxbWeJ080c2unVr3EoF5ZaSl1wsi9bdTTpLm1pFXK/ssi6v59p4iMDH7Cvsae86H8DoZbEB6Pii5wYzIvElq6JEm6rlnO4KYuoGshjYTkeByN1azQBEqAKBgVaQIRQ3pW7o5MJXoC+OheEwpjUbnjWMXFhrSjdU6yCWdUJNDSfvTGLjRjI/8hcJ8DNEV6/1mZjAAWP/yQWhOOOw69Z0b5nCgWckHP/+cSHzuliQ6GaeVg=="}
}

List issuances

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

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. Required. You can repeat this parameter up to 10 times to search multiple domains at once. Issuances that match any of the queried domains are returned.
`include_subdomains`	Also include issuances that are valid for sub-domains (of any depth) of `domain`. `true` or `false`. Default: false.
`match_wildcards`	Also include 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`. `true` or `false`. Default: false.
`expired`	Include expired issuances. `true` or `false`. Default: false. Setting this option to true requires you to subscribe to a Cert Spotter API plan that supports expired certificates.
`after`	Return issuances that were discovered by Cert Spotter since the issuance with the specified ID. If not specified, return issuances discovered since the beginning of time.
`expand`	Include the given field in the response. Repeat this parameter to expand multiple fields.

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

Issuance Pagination

The Cert Spotter 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 Cert Spotter has discovered new issuances matching your query, they will be returned. You can then request subsequent pages until another empty response is returned.

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.

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

Authentication

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

When you're ready to launch in production, we ask that you sign up for an account, which is free for up to 1,000 queries an hour, and authenticate to the API using one the following methods:

Specify your SSLMate API key using an OAuth2 Bearer Token.
Specify your SSLMate API key as the username using HTTP Basic Authentication. Use an empty password.
Specify your SSLMate username and password using HTTP Basic Authentication.

Your API key can be found on your account page.

Examples:

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

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

Compatibility

SSLMate will only make backwards-compatible changes to this API (e.g. adding new endpoints, adding new fields to responses, adding new optional parameters to requests).

SSLMate

Cert Spotter APIv1