Authorize Public Key

When you authorize a public key, Cert Spotter won't notify you about certificates that certify the key. Any certificates for the key that have already been discovered will be removed from your unknown certificates list.

When you authorize a public key, you must specify which DNS names are authorized to use the key. Cert Spotter will still notify you about certificates that use the key if they are valid for other DNS names.

To authorize a public key, send a POST request to https://sslmate.com/api/v3/monitoring/known_keys. The posted body can be one of the following:

• PEM-encoded CSR. If you upload a PEM-encoded CSR with a Content-Type of application/x-pem-file, SSLMate will authorize the CSR's public key for every DNS name in the CSR's subjectAltName extension.

• DER-encoded CSR. If you upload a DER-encoded CSR with a Content-Type of application/pkcs10, SSLMate will authorize the CSR's public key for every DNS name in the CSR's subjectAltName extension.

• JSON object. You can upload a JSON object with a Content-Type of application/json that contains the following fields:

  • pubkey_sha256 (string): The lowercase hex-encoded SHA-256 hash of the public key to authorize. The hash is computed over the DER-encoded subject public key info.
  • dns_names (array of strings): The DNS names for which the public key will be authorized.

Authorize Certificate

When you authorize a certificate, Cert Spotter won't notify you if the certificate is later discovered in a Certificate Transparency log. If Cert Spotter has already discovered the certificate, the certificate will be removed from your unknown certificates list.

There is an inherent race condition when authorizing certificates - if Cert Spotter has already discovered the certificate by the time you authorize it, you will have already received a notification. For this reason, we recommend that you authorize public keys instead, by uploading CSRs to Cert Spotter before you submit them to your certificate authority. If you have to authorize by certificate, we recommend you do so immediately after receiving the certificate from your certificate authority, to maximize the probability that Cert Spotter has not yet discovered it.

To authorize a certificate, send a POST request to https://sslmate.com/api/v3/monitoring/known_certs. The posted body can be one of the following:

• PEM-encoded certificate. If you upload a PEM-encoded certificate with a Content-Type of application/x-pem-file or application/pem-certificate-chain, SSLMate will authorize the certificate.

• DER-encoded certificate. If you upload a DER-encoded certificate with a Content-Type of application/pkix-cert, SSLMate will authorize the certificate.

• JSON object (for advanced users only). You can upload a JSON object with a Content-Type of application/json that contains the following field:

  • tbs_sha256 (string): The lowercase hex-encoded SHA-256 hash of the TBSCertificate to authorize. The hash is computed over the "DER-encoded TBSCertificate component of the Precertificate," per RFC6962, Section 3.2.

  Since constructing the TBSCertificate is complex, we recommend uploading a certificate instead of a JSON object.

Authentication

• 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.

Your API key can be found on your account page.

Authentication examples:

curl -H "Authorization: Bearer 123_sampleapikey" https://sslmate.com/api/v3/monitoring/known_keys

curl -u 123_sampleapikey: https://sslmate.com/api/v3/monitoring/known_keys