Security Badges

Embed a security badge on your website or README. The badge shows the letter grade and score from your domain's most recent completed scan, rendered as an SVG you can hotlink directly.

The badge mirrors the stored result of the domain's last full scan — the same number, from the same place, as your report and dashboard. It does not run its own check, so the badge and the report can never disagree.

The default style is the ComplianceLayer card:

SVG Badge Endpoint

<!-- Embed in HTML (default card style) -->
<img
  src="https://api.compliancelayer.net/v1/badge/example.com.svg"
  alt="Security Grade"
/>

<!-- Compact strip for tighter layouts -->
<img
  src="https://api.compliancelayer.net/v1/badge/example.com.svg?style=flat"
  alt="Security Grade"
/>

Publishing Your Badge

# Publish
curl -X PATCH "https://api.compliancelayer.net/v1/domains/123/badge" \
  -H "Authorization: Bearer cl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badge_enabled": true}'

# Unpublish
curl -X PATCH "https://api.compliancelayer.net/v1/domains/123/badge" \
  -H "Authorization: Bearer cl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badge_enabled": false}'

JSON Badge Endpoint

curl "https://api.compliancelayer.net/v1/badge/example.com.json" \
  -H "Authorization: Bearer cl_YOUR_API_KEY"

Rate Limiting

Both badge endpoints are limited to 30 requests per minute per IP address, which prevents bulk enumeration. Exceeding it returns 429 with {"detail": "Rate limit exceeded"}. This is separate from your plan's API rate limits.

Because the SVG is served with Cache-Control: public, max-age=3600, embedding a badge on a high-traffic page does not consume your allowance — browsers and CDNs serve it from cache.

Badge Grades

The badge uses the same grade bands as the full report — one ladder for the whole product:

There are no plus or minus grades. The two styles use the same ladder; the card's colors are brightened for its dark background.

If the last scan could not assess enough of the domain to grade it honestly, the stored result is INCOMPLETE. The SVG then renders "Not assessed" instead of a letter, and any custom rendering of the JSON response must handle that value — a lookup keyed only on A-F will fail the first time a scan cannot complete.

Custom Badge Implementation

To render your own badge from the JSON endpoint, fetch it on the server and pass only the result to the browser. Both examples below keep the API key server-side and treat 404as "no badge to show".

const express = require('express');
const app = express();

// Server-side proxy: the API key never leaves the server.
// Never call the .json endpoint from browser JavaScript.
app.get('/api/security-badge/:domain', async (req, res) => {
  const response = await fetch(
    `https://api.compliancelayer.net/v1/badge/${req.params.domain}.json`,
    { headers: { 'Authorization': `Bearer ${process.env.COMPLIANCELAYER_API_KEY}` } }
  );

  if (response.status === 404) {
    // Not one of your domains, or no completed scan yet — nothing to show.
    return res.status(404).json({ error: 'No badge for this domain' });
  }
  if (!response.ok) {
    return res.status(502).json({ error: 'Badge lookup failed' });
  }

  const badge = await response.json();

  // Mirror the upstream 1-hour cache so you stay well inside 30 req/min per IP
  res.set('Cache-Control', 'public, max-age=3600');
  res.json(badge);
});

Best Practices

1. Cache Badge Images

• SVG badges are cached for 1 hour by ComplianceLayer
• Your CDN should cache badges for at least 30 minutes
• Respect the Cache-Control header rather than cache-busting the URL

2. Provide Alt Text

<img
  src="https://api.compliancelayer.net/v1/badge/example.com.svg"
  alt="ComplianceLayer security grade for example.com"
/>

Keep the grade out of the alt text unless you regenerate the page when the badge changes, otherwise the two will drift apart. The SVG already carries an accessible aria-label and <title> with the current grade and score.

3. Link to ComplianceLayer

Make badges clickable so visitors can learn what the grade means:

<a
  href="https://compliancelayer.net"
  target="_blank"
  rel="noopener noreferrer"
>
  <img
    src="https://api.compliancelayer.net/v1/badge/example.com.svg"
    alt="ComplianceLayer security grade for example.com"
  />
</a>

There is no public page showing your stored report, so link to the site rather than constructing a report URL. To share full scan results, generate a report through the scan API and host it yourself.

4. Keep Expectations Straight

• The badge shows the result of the domain's most recent completed scan — running a new scan updates it (allowing up to an hour of edge caching)
• The badge never runs a scan of its own; a domain with no completed scan has no badge
• Unpublishing takes effect immediately at the API, though embedded copies may persist in caches for up to an hour

Example Implementations

Footer Badge

<footer>
  <div class="security-badge-container">
    <p>Security Powered by ComplianceLayer</p>
    <a href="https://compliancelayer.net">
      <img
        src="https://api.compliancelayer.net/v1/badge/example.com.svg"
        alt="ComplianceLayer security grade for example.com"
      />
    </a>
  </div>
</footer>

README Badge

# MyApp

![Security Grade](https://api.compliancelayer.net/v1/badge/myapp.com.svg?style=flat)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

Secure, reliable cloud platform...

Related Topics

• Running Scans - Full 15-module assessments
• Monitoring Domains - Automated scan scheduling
• API Reference - Complete endpoint documentation