← Back to Quick Start

Inspect Any Website's SSL Certificate

Check certificate validity, expiration dates, issuer details, and protocol support for any hostname.

What you'll learn

  • How to retrieve SSL certificate details for any domain
  • How to check certificate expiration and days remaining
  • How to detect self-signed certificates and weak protocols
  • How to set up automated monitoring for certificate expiry

Prerequisites

Step 1: Your first call

Check the SSL certificate for google.com:

curl -s -X POST /api/v1/ssl/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "hostname": "google.com",
    "port": 443
  }' | python3 -m json.tool

Expected response:

{
  "hostname": "google.com",
  "port": 443,
  "valid": true,
  "selfSigned": false,
  "issuer": {
    "commonName": "GTS CA 1C3",
    "organization": "Google Trust Services LLC",
    "country": "US"
  },
  "subject": {
    "commonName": "*.google.com",
    "organization": "Google LLC"
  },
  "serialNumber": "7A:3B:4C:5D:6E:7F:...",
  "signatureAlgorithm": "SHA256withRSA",
  "notBefore": "2026-02-15T08:00:00Z",
  "notAfter": "2026-05-10T08:00:00Z",
  "daysUntilExpiry": 45,
  "subjectAlternativeNames": ["*.google.com", "google.com", "*.google.co.uk"],
  "protocol": "TLSv1.3",
  "cipherSuite": "TLS_AES_256_GCM_SHA384",
  "chainLength": 3,
  "chainValid": true,
  "processingTimeMs": 340
}

Step 2: Understanding the response

valid Whether the certificate is currently valid (not expired, chain trusted, hostname matches).
selfSigned Whether the certificate is self-signed (not trusted by browsers by default).
daysUntilExpiry Days until the certificate expires. Negative means already expired.
protocol Negotiated TLS version (TLSv1.2, TLSv1.3). Older protocols indicate security risk.
chainValid Whether the full certificate chain (root CA to leaf) is valid and trusted.
subjectAlternativeNames All hostnames the certificate is valid for (wildcard and explicit).

Step 3: Common use cases

Detecting an expiring certificate

Check a site whose certificate is close to expiry:

curl -s -X POST /api/v1/ssl/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"hostname": "expiring-cert-demo.example.com"}'
{
  "hostname": "expiring-cert-demo.example.com",
  "valid": true,
  "daysUntilExpiry": 3,
  "notAfter": "2026-03-29T00:00:00Z",
  ...
}

When daysUntilExpiry is below your threshold (e.g., 30 days), trigger a renewal alert.

Self-signed certificate detection

curl -s -X POST /api/v1/ssl/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"hostname": "self-signed.badssl.com"}'
{
  "hostname": "self-signed.badssl.com",
  "valid": false,
  "selfSigned": true,
  "chainValid": false,
  "issuer": {
    "commonName": "*.badssl.com",
    "organization": "BadSSL"
  },
  "daysUntilExpiry": 180,
  "processingTimeMs": 290
}

Custom port

Check SSL on a non-standard port (e.g., an SMTP server on 587):

curl -s -X POST /api/v1/ssl/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"hostname": "smtp.gmail.com", "port": 587}'

Step 4: Handling errors

Connection refused / timeout

curl -s -X POST /api/v1/ssl/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"hostname": "no-ssl-here.example.com"}'
{
  "hostname": "no-ssl-here.example.com",
  "valid": false,
  "error": "CONNECTION_FAILED",
  "message": "Could not establish SSL connection to no-ssl-here.example.com:443",
  "processingTimeMs": 5000
}

Invalid hostname

{
  "error": "VALIDATION_ERROR",
  "message": "hostname: must be a valid domain name",
  "status": 400
}

Step 5: Integration tips

Python expiry monitor

import requests

API_BASE = ""
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

DOMAINS_TO_MONITOR = [
    "myapp.com",
    "api.myapp.com",
    "admin.myapp.com"
]
ALERT_THRESHOLD_DAYS = 30

def check_ssl(hostname):
    resp = requests.post(
        f"{API_BASE}/api/v1/ssl/check",
        json={"hostname": hostname},
        headers=HEADERS, verify=False
    )
    resp.raise_for_status()
    return resp.json()

for domain in DOMAINS_TO_MONITOR:
    result = check_ssl(domain)
    days = result.get("daysUntilExpiry", 0)
    if days < ALERT_THRESHOLD_DAYS:
        print(f"ALERT: {domain} expires in {days} days!")
    else:
        print(f"OK: {domain} -- {days} days remaining")

Bulk check (up to 20 hosts)

curl -s -X POST /api/v1/ssl/check-bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "targets": [
      {"hostname": "google.com"},
      {"hostname": "github.com"},
      {"hostname": "self-signed.badssl.com"}
    ]
  }'

Next steps