SSL Toolkit Logo
Tools Features Compare FAQ Login

SSL Status Badge

Embed a live certificate status badge for any domain

About the SSL Status Badge

The badge queries the domain's certificate over TLS and renders the result as a small SVG image. It shows days remaining while the certificate is healthy, and switches to expired or unknown when something is wrong, using the familiar green/amber/red convention. Because it is a plain image, it works in GitHub READMEs, documentation sites, dashboards and status pages without any script. Results are cached for one hour, so embedding the badge on a heavily visited page does not hammer the target server.

How to Use

  1. 1Enter the domain you want to badge, without a scheme. A hostname such as example.com is checked over HTTPS on port 443.
  2. 2Pick a style and, if you like, change the label. The preview updates to show exactly what visitors will see.
  3. 3Copy the Markdown, HTML or reStructuredText snippet and paste it into your README or documentation.
  4. 4The badge refreshes on its own once an hour, so it stays accurate without anything to maintain.

Use Cases

  • Open source READMEs — a badge that turns red when a release certificate lapses, visible to every visitor.
  • Status and changelog pages — show visitors at a glance that the site is properly secured.
  • Internal dashboards and runbooks — the SVG endpoint can be used directly as an image source.
  • Customer trust pages — answer the "is this site still safe?" question before a support ticket arrives.
  • Release notes and deployment docs — monitor a domain you just moved while DNS and caches settle.

Colour thresholds

Green — more than 45 days remaining.
Yellow — 22 to 45 days remaining; time to plan the renewal.
Orange — 8 to 21 days remaining.
Red — 7 days or fewer, or expired.
Grey — the domain could not be reached or has no certificate.

Frequently Asked Questions

No. The badge is a small SVG served with a one-hour cache header, so visitors' browsers and any CDN in between reuse it. Keep the image small and it will be a negligible part of your page weight.
Technically yes, since the badge only reads the publicly presented certificate. Please point badges at domains you own or maintain - embedding a badge for someone else's site risks mislabeling its status.
The tool could not complete a TLS handshake with the domain on port 443 - usually a DNS problem, a firewall, a non-standard port, or a server that does not offer TLS. Use the SSL Checker for the detailed error.
No, and it is worth being clear about that. A badge can honestly show expiry and issuer, which are facts about a certificate. It cannot express a security posture, which depends on protocol, cipher, chain and configuration — none of which fit in a small image. Treating a green badge as a security claim is the failure mode to avoid; it is a maintenance indicator and nothing more.
Because it is the one thing a badge can usefully warn about, and it is discrete rather than a judgement. Everyone reaches the same answer about whether a certificate is current, so there is nothing to argue about. Putting an expiry on a badge turns it into a prompt to act before the date rather than after, which is the useful contribution it can make.
More often than you think. A badge is a snapshot, and a snapshot goes stale silently — nothing tells you it stopped updating. Generating on a schedule tied to the renewal process is the practical approach, and treating an unexpectedly old timestamp as a finding is the discipline that makes it worth having rather than decoration.
The hosted badge is convenient and always current when requested. Generating your own lets you control what appears on it and lets you store the history, which is useful if you want to demonstrate a change over time. Neither is better in principle — what matters is that whatever you use actually reflects the live certificate rather than a cached image of one.
Not fundamentally — it reads the same facts. What it adds is visibility where you already are, since a badge in a status page or dashboard is seen by people who would never run a checker. That is a real benefit for communication, but it is presentation rather than additional assurance, and it should complement monitoring rather than substitute for it.

Technical Details

Badge endpoint

  • GET /badge/<domain>.svg — the .svg suffix is optional
  • ?style= flat, flat-square, for-the-badge or plastic
  • ?label= up to 32 characters, ?port= any TLS port
  • Returns image/svg+xml plus an X-Badge-Status header: valid, expiring, critical, expired or unknown

Colour thresholds

  • Green — valid, more than 45 days remaining
  • Yellow — expiring, 22 to 45 days remaining
  • Orange — critical, 8 to 21 days remaining
  • Red — critical, 7 days or less, or already expired
  • Grey — unknown: host unreachable, TLS failed, or an invalid domain

Caching and abuse protection

  • Cache-Control: public, max-age=3600, so a visitor fetches each badge at most once an hour
  • A server-side cache uses the same one-hour TTL, so repeat hits never touch the network
  • Deliberately not rate limited: a 429 would break a badge embedded on someone else's page
  • Each distinct domain, port and label combination is cached separately

What is checked

  • The certificate the server actually presents on that host and port
  • Its notAfter date, converted into days remaining
  • Wildcards and single-label hostnames are rejected because they cannot be resolved
  • A certificate that cannot be retrieved always renders as unknown, never as valid

What The Badge Reads

A badge is a summary, and a summary is only useful if it reports something measured. This page states exactly what is behind the image it serves.

  1. 1Open a connection and read the certificate — validity dates, issuer and the names it covers. Those are the facts a badge can honestly represent, because they are discrete and verifiable.
  2. 2Render those facts as an image, with the expiry most prominent since that is what a badge is usually for. Everything shown on it comes from the live connection made when it was generated.
  3. 3Keep it to what a badge can carry. A small image cannot express a security posture, and a badge implying one would be misleading. Expiry and issuer are facts; everything else belongs in a report you can read.

A badge shows the state at the moment it was generated, not continuously. If you embed one, regenerate it on a schedule — otherwise the most likely thing it can be showing is a stale success.

Tips & Best Practices

  • •Add the badge to your README so reviewers can see certificate health at a glance.
  • •Use flat-square when the surrounding design is square-cornered.
  • •Combine the badge with expiry alerts so a yellow badge triggers a real reminder.
  • •Set an explicit alt attribute so the badge is accessible.

Related Tools

SSL Checker Expiry Watch Expiry Alerts Certificate Monitor Batch Checker Inventory Manager