Certificate Health

The certificate health endpoints let you check the SSL certificate status of any monitor with the certificate health check enabled, and browse all certificates that have been detected over time.

You'll need a monitor ID for these endpoints.

Example request:

$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/certificate-health/1 \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

All endpoints below follow the same authentication pattern.

Get certificate health #

GET /api/certificate-health/{monitorId}

Returns the current certificate health status, including certificate details, a list of checks we performed, and the full certificate chain.

Here's what the response looks like:

{
  "certificate_details": {
    "issuer": "Let's Encrypt Authority X3",
    "valid_from": "2019-09-10 15:16:01",
    "valid_until": "2019-12-09 15:16:01"
  },
  "certificate_checks": [
    {
      "type": "notFound",
      "label": "Certificate is present",
      "passed": true
    },
    {
      "type": "expiresSoon",
      "label": "Will not expire soon",
      "passed": true
    },
    {
      "type": "coversWrongDomain",
      "label": "Covers the right domain",
      "passed": true
    },
    "..."
  ],
  "certificate_chain_issuers": [
    "US, Let's Encrypt, Let's Encrypt Authority X3",
    "Digital Signature Trust Co., DST Root CA X3"
  ]
}

• certificate_details: basic information about the current certificate (issuer, validity dates in UTC)
• certificate_checks: array of checks we performed. Each has a type, label, and passed boolean
• certificate_chain_issuers: names of all issuers in the complete certificate chain

To determine the overall health, look for checks with "passed": false.

The possible check types are: notFound, expiresSoon, coversWrongDomain, doesNotConnectWithRootCertificate, notYetActive, isSelfSigned, usesInvalidHash, hasExpired, hasChanged, lifetimeTooLong, couldNotConnectToHost, hostDoesNotExist, noCertificateInstalled, couldNotDownloadCertificate.

Get a detected certificate #

GET /api/monitors/{monitorId}/detected-certificates/{detectedCertificateId}

Returns a single detected certificate by its ID. This includes the full certificate details and metadata.

Here's what the response looks like:

{
  "id": 123,
  "monitor_id": 1,
  "fingerprint": "abcd1234567890abcd1234567890abcd12345678",
  "certificate_details": {
    "issuer": "Let's Encrypt Authority X3",
    "domain": "example.com",
    "additional_domains": [
      "www.example.com"
    ],
    "valid_from": "2023-10-01T12:00:00Z",
    "valid_until": "2024-01-01T12:00:00Z",
    "days_until_expiration": 45,
    "signature_algorithm": "sha256WithRSAEncryption",
    "is_valid": true,
    "is_expired": false
  },
  "created_at": "2023-10-01T12:30:00Z",
  "updated_at": "2023-10-01T12:30:00Z"
}

• id: unique identifier for this detected certificate
• monitor_id: the monitor this certificate was detected on
• fingerprint: SHA-1 fingerprint of the certificate
• certificate_details: certificate metadata
  • issuer: the certificate authority that issued the certificate
  • domain: the primary domain the certificate covers
  • additional_domains: other domains covered by the certificate
  • valid_from: when the certificate becomes valid (UTC)
  • valid_until: when the certificate expires (UTC)
  • days_until_expiration: days remaining until expiration
  • signature_algorithm: the signing algorithm used
  • is_valid: whether the certificate is currently valid
  • is_expired: whether the certificate has expired
• created_at: when Oh Dear first detected this certificate (UTC)
• updated_at: when this record was last updated (UTC)

List detected certificates #

GET /api/monitors/{monitorId}/detected-certificates

Returns a paginated list of all certificates detected for a monitor, including historical certificates. Each item follows the same shape as the single response above.

{
  "data": [
    {
      "id": 123,
      "fingerprint": "abcd1234...",
      "certificate_details": {
        "issuer": "Let's Encrypt Authority X3",
        "..."
      },
      "..."
    }
  ],
  "links": { "..." },
  "meta": { "..." }
}

Query parameters:

• filter[fingerprint] (string, optional) -- filter by certificate fingerprint
• sort (string, optional) -- sort by created_at, updated_at, or fingerprint. Prefix with - for descending order (e.g., -created_at)