Certificate Transparency API

The Certificate Transparency API allows you to subscribe domains for certificate alerts and phishing alerts, and to search for newly issued certificates.

The API consists of the following endpoints:

Certificate Alerts

Subscribing/Unsubscribing Domains

In order for your certificate alert webhook to work correctly, you must subscribe one or more domains for certificate alerts.

To subscribe/unsubscribe domains, send a POST request to the /{your-app-id}/subscribed_domains edge and include one of the following parameters and values:

• subscribe — A list of domains to subscribe for certificate alerts
• unsubscribe — A list of domains to unsubscribe from certificate alerts

For example, to subscribe facebook.com for certificate alerts:

curl -i -X POST \
  "https://graph.facebook.com/457084771331516/subscribed_domains" \
  -F "subscribe=facebook.com" \
  -F "access_token=your-app-access-token"

If successful, this would return the following response:

{
  "success": "true"

}

Listing Subscribed Domains

To get a list of domains subscribed for certificate alerts, send a GET request to the /{your-app-id}/subscribed_domains edge and optionally include the fields=domain parameter and value.

GET https://graph.facebook.com/457084771331516/subscribed_domains
      &fields=domain

This would return a list domains and subscription IDs:

{
  "data": [
    {
      "domain": "fb.com",
      "id": "588710074585924"
    },
    {
      "domain": "f8.com",
      "id": "573476006109678"
    },
    {
      "domain": "digicert.com",
      "id": "1592061337518800"
    },
    {
      "domain": "facebook.com",
      "id": "1567436076683534"
    }
  ],
  "paging":
    {
      "cursors":
        {
          "before": "QVF...",
          "after": "QVF..."
        }
    }
}

Phishing Alerts

Subscribing/Unsubscribing Domains

In order for your phishing alert webhook to work correctly, you must subscribe one or more domains for phishing alerts.

To subscribe/unsubscribe domains, send a POST request to the /{your-app-id}/subscribed_domains_phishing edge and include one of the following parameters and values:

• subscribe — A list of domains to subscribe for phishing alerts.
• unsubscribe — A list of domains to unsubscribe from phishing alerts.

For example, to subscribe legit-domain.com for phishing alerts:

curl -i -X POST \
  "https://graph.facebook.com/457084771331516/subscribed_domains_phishing" \
  -F "subscribe=legit-domain.com" \
  -F "access_token=your-app-access-token"

If successful, this would return the following response:

{
  "success": "true"
}

Listing Subscribed Domains

To get a list of domains subscribed for phishing alerts, send a GET request to the /{your-app-id}/subscribed_domains_phishing edge and optionally include the fields=domain parameter and value.

GET https://graph.facebook.com/457084771331516/subscribed_domains_phishing
      &fields=domain

This would return a list domains and subscription IDs:

{
  "data": [
    {
      "domain": "fb.com",
      "id": "588710074585924"
    },
    {
      "domain": "f8.com",
      "id": "573476006109678"
    },
    {
      "domain": "digicert.com","id": "1592061337518800"
    },
    {
      "domain": "facebook.com",
      "id": "1567436076683534"}
  ],
  "paging":
    {
      "cursors":
        {
          "before": "QVF...",
          "after": "QVF..."
        }
    }
}

Searching For Certificates

To search for newly issued certificates, send a GET request to the /certificates edge and include the query parameter along with the name of the domain you want to query. Normally you will only need to do this when you receive a webhook notification containing a certificate alert or phishing alert.

For example, here's how to see if any new certificates have been issued for facebook.com:

GET https://graph.facebook.com/certificates
  ?query=facebook.com

This would return a default response that would look something list this:

{
  "data": [
    {
      "certificate_pem": "-----BEGIN CERTIFICATE-----
MIIH5DCCBsygAwIBAgIQDACZt9eJyfZmJjF+vOp8HDANBgkqhkiG9w0BAQsFADBw
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMS8wLQYDVQQDEyZEaWdpQ2VydCBTSEEyIEhpZ2ggQXNz
dXJhbmNlIFNlcnZlciBDQTAeFw0xNjEyMDkwMDAwMDBaFw0xODAxMjUxMjAwMDBa
MGkhMRMwEQYDVQQHEwpNZW5sbyBQYXJrMRcwFQYDVQQKEw5GYWNlYm9vaywgSW5j
LjEXMBUGA1UEAwwOKi5mHwYDVR0jBBgwFoAUUWj/kK8CB3U8zNllZGKiErhZcjsw
YWNlYm9vay5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASg8YyvpzmIaFsT
Vg4VFbSnRe8bx+WFPCsE1GWKMTEi6qOS7WSdumWB47YSdtizC0Xx/wooFJxP3HOp
s0ktoHbTo4IFSjCCBUYwHwYDVR0jBBgwFoAUUWj/kK8CB3U8zNllZGKiErhZcjsw
HQYDVR0OBBYEFMuYKIyhcufiMqmaPfINoYFWoRqLMIHHBgNVHREEgb8wgbyCDiou
ZmFjZWJvb2suY29tgg4qLmZhY2Vib29rLm5ldIIIKi5mYi5jb22CCyouZmJjZG4u
bmV0ggsqLmZic2J4LmNvbYIQKi5tLmZ
-----END CERTIFICATE-----",
      "id": "1662768163744657"
    }
  ]
}

To have specific fields returned, append the fields parameter and list the fields you want included in the response. For example:

GET https://graph.facebook.com/certificates?query=facebook.com
    &fields=cert_hash_sha256,domains,issuer_name,certificate_pem

This would return something like this:

{
  "data": [
    {
      "cert_hash_sha256": "152151b387412a95ab90fd4664f2d98880408e9e43913124e4c91226a483386b",
      "domains": [
        "*.facebook.com",
        "*.facebook.net",
        "*.fb.com",
        "*.fbcdn.net",
        "*.fbsbx.com",
        "*.m.facebook.com",
        "*.messenger.com",
        "*.xx.fbcdn.net",
        "*.xy.fbcdn.net",
        "*.xz.fbcdn.net",
        "facebook.com",
        "fb.com",
        "messenger.com"
      ],
      "issuer_name": "/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert SHA2 High Assurance Server CA",
      "certificate_pem": "-----BEGIN CERTIFICATE-----
MIIH5DCCBsygAwIBAgIQDACZt9eJyfZmJjF+vOp8HDANBgkqhkiG9w0BAQsFADBw
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
d3cuZGlnaWNlcnQuY29tMS8wLQYDVQQDEyZEaWdpQ2VydCBTSEEyIEhpZ2ggQXNz
dXJhbmNlIFNlcnZlciBDQTAeFw0xNjEyMDkwMDAwMDBaFw0xODAxMjUxMjAwMDBa
MGkhMRMwEQYDVQQHEwpNZW5sbyBQYXJrMRcwFQYDVQQKEw5GYWNlYm9vaywgSW5j
LjEXMBUGA1UEAwwOKi5mHwYDVR0jBBgwFoAUUWj/kK8CB3U8zNllZGKiErhZcjsw
YWNlYm9vay5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASg8YyvpzmIaFsT
Vg4VFbSnRe8bx+WFPCsE1GWKMTEi6qOS7WSdumWB47YSdtizC0Xx/wooFJxP3HOp
s0ktoHbTo4IFSjCCBUYwHwYDVR0jBBgwFoAUUWj/kK8CB3U8zNllZGKiErhZcjsw
HQYDVR0OBBYEFMuYKIyhcufiMqmaPfINoYFWoRqLMIHHBgNVHREEgb8wgbyCDiou
ZmFjZWJvb2suY29tgg4qLmZhY2Vib29rLm5ldIIIKi5mYi5jb22CCyouZmJjZG4u
bmV0ggsqLmZic2J4LmNvbYIQKi5tLmZ
-----END CERTIFICATE-----",
      "id": "1662768163744657"
    }
  ]
}

Fields

The /certificates edge can return the following fields:

• authority_key_identifier — The certificate issuer's subjectKeyIdentifier.
• basic_constraints — Indicates whether a cert is a signing CA.
• cert_hash_md5 — The resultant MD5 hash.
• cert_hash_sha1 — The resultant SHA-1 hash.
• cert_hash_sha256 — The resultant SHA-256 hash.
• certificate_pem — Base64 encoded certificate in PEM format.
• domains — Domains extracted from altSubjectNames extension of X509 TLS Certificates.
• extended_key_usage — Extended key usage field of the certificate.
• extensions — Standard certificate extensions as defined in RFC 5280.
• id — The certificate node object's ID.
• issuer_name — Issuer Name field.
• key_usage — Key Usage field.
• not_valid_after — End of cert validity as a UNIX timestamp.
• not_valid_before — Start of cert validity as a UNIX timestamp.
• public_key_algorithm — Name of the algorithm used for creating PK.
• public_key_hash_sha256 — SHA-256 hash function computed on the Public Key.
• public_key_pem — PEM of the Public Key.
• public_key_size — Key size in bits.
• public_key_values — Additional Public Key values.
• serial_number — Serial Number of the certificate.
• signature_algorithm — Signature Algorithm.
• signature_value — Digital signature computed upon the ASN.1 DER encoded certificate.
• subject_key_identifier — Subject Key identifier.
• subject_name — Subject Name.
• version — Version of the encoded certificate.