HeaderShield
FeaturesComparePricingDashboardHelpRedeem
Get free key

Help & Knowledge Hub

Everything you need to scan, grade and harden your sites' security headers — quick start, feature map, FAQs and troubleshooting.

Quick start

  1. 1

    Scan your first site

    Paste any URL into the scanner on the homepage. You get an A+ to F grade, a per-header breakdown (CSP, HSTS, clickjacking, MIME sniffing, referrer and permissions policies, COOP/CORP), TLS certificate expiry, cookie flags and the DNS & Email Security posture — no account needed.

  2. 2

    Get your API key

    Sign up on /signup for a free key (10 scans per month, no credit card), or redeem a lifetime-deal coupon on /redeem — it activates Enterprise-level lifetime access and returns your key instantly. Keep the key secret; the dashboard never stores it server-side.

  3. 3

    Call the API

    Send your key in the X-API-Key header (or as "Authorization: Bearer <key>"): curl "https://headershield.dev/api/v1/scan?url=https://example.com" -H "X-API-Key: hsh_...". The full REST surface is described by the OpenAPI 3.1 document at /api/openapi.json.

  4. 4

    Read the result

    Every finding carries its status (pass/warn/fail), points, a plain-English explanation and a copy-paste fixSnippet for Nginx, Apache, Cloudflare, Next.js and vercel.json. The dnsPosture section reports SPF, DMARC, DKIM, CAA and DNSSEC — each one found, missing or unknown (unknown = the DNS lookup did not complete, never a guess).

  5. 5

    Automate it

    Paid plans can register monitors (POST /api/v1/monitors) so sites are re-scanned on a schedule, with email alerts and signed webhooks on downgrades (Premium+). Pull a branded HTML report from /api/v1/report, embed the public grade badge in your README, or wire the GitHub Action from /docs to fail builds below your grade threshold.

Features & API map

FeaturePlanAPI
Security-header scan + A+–F gradeAll plans (Free: 10 scans/mo)GET /api/v1/scan
TLS certificate expiry + cookie flagsAll plans (in every scan)GET /api/v1/scan
DNS & Email Security posture (SPF/DMARC/DKIM/CAA/DNSSEC)All plans (in every scan)GET /api/v1/scan → dnsPosture
Copy-paste fix snippets (Nginx/Apache/Cloudflare/Next.js/vercel.json)All plansGET /api/v1/scan → findings[].fixSnippet
Scheduled monitoring + alertsBasic: 3 sites · Premium: 20 · Business/Lifetime: 100POST /api/v1/monitors
Signed webhooks (scan.completed, monitor.changed)Premium and abovePUT /api/v1/webhooks
Bulk scan (batch of domains)Premium: 20/batch · Business/Lifetime: 50/batchPOST /api/v1/bulk/scan
Branded HTML security reportAny API key (counts as one scan)GET /api/v1/report
Public share page + grade badgeFree, no key neededPOST /api/share · GET /api/badge/{token}
README grade badge (live scan)Free, no key neededGET /api/badge?url=example.com

Frequently asked questions

The grade maps your 0–100 score onto letters: A+ (95+), A (85+), B (70+), C (55+), D (40+), E (25+), F (below 25). The score is the weighted sum of the header checks — CSP is worth 25 points, HSTS 20, clickjacking protection and X-Content-Type-Options 10 each, Referrer-Policy and Permissions-Policy 10 each, COOP and CORP 5 each, and 5 points for not leaking your stack via Server/X-Powered-By.
Content-Security-Policy, Strict-Transport-Security, X-Frame-Options (or CSP frame-ancestors), X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy, plus Server/X-Powered-By information leaks. Every scan also audits cookie flags (Secure, HttpOnly, SameSite), checks the TLS certificate expiry, probes the http→https redirect and runs a granular CSP analysis.
Content-Security-Policy is an allowlist that tells the browser which sources may run scripts or load resources — the strongest defence against XSS. You get 'warn' (half points) when a CSP exists but script execution is weakened by 'unsafe-inline' or 'unsafe-eval' in script-src/default-src, because most XSS payloads still execute. Move inline scripts to nonces or hashes. Note: 'unsafe-inline' only in style-src does NOT lower your grade — it is not an XSS vector.
Five DNS-level controls, resolved over DNS-over-HTTPS: SPF (a v=spf1 TXT record and how strict its all-mechanism is), DMARC (the _dmarc TXT record and its p= policy), DKIM (a signing key at the common selectors default, google, selector1, selector2, k1), CAA (which certificate authorities may issue for the domain) and DNSSEC (whether the resolver could cryptographically validate the answers). Each check is tri-state: found, missing, or unknown when the lookup did not complete in time.
DMARC tells receiving mail servers what to do with messages that fail SPF/DKIM alignment for your domain — the record lives in a TXT entry at _dmarc.yourdomain.com. p=none only monitors, p=quarantine sends failures to spam, p=reject blocks them outright. Without an enforced DMARC policy, anyone can spoof email from your domain. Start with p=none plus a rua= reporting address, then move to quarantine and reject.
Go to /redeem, enter your coupon code and email, and submit. Your account is upgraded to lifetime Enterprise access (unlimited scans, no recurring billing) and your API key is shown once in the response — copy it immediately. Redemption is idempotent: re-submitting the same code for the same email is safe, but a code can only be claimed once.
The key (format hsh_...) is returned exactly once — by /signup for free keys and by /redeem for coupon redemptions. HeaderShield does not display it again for security. Paste it into /dashboard to see your plan, usage and recent requests (the dashboard keeps it in your browser's local storage only). If you lose it, sign up again or contact support.
Free: 10 scans/month, no monitors. Basic ($9/mo): 500 scans/month, 3 monitors. Premium ($29/mo): unlimited scans, 20 monitors, webhooks, bulk scan (20 domains/batch). Business ($79/mo): unlimited scans, 100 monitors, bulk 50/batch, white-label reports. Lifetime (coupon): Enterprise level — unlimited scans, 100 monitors, all Premium+ features, forever. Failed scans never consume quota.
No. A scan that errors (unreachable target, SSRF-blocked address, invalid URL) returns a 400 SCAN_FAILED envelope and does not increment your monthly usage.
Yes — two flavours, both public and key-less. Live badge: ![Security headers](https://headershield.dev/api/badge?url=example.com) re-scans on a 1-hour cache. Snapshot badge: share a result (POST /api/share) and embed /api/badge/{token}, which shows the frozen grade of that snapshot and links nicely to your public /r/{token} page.

Troubleshooting

The API key is missing or wrong. Send it exactly as received (hsh_ prefix included) in the X-API-Key header, or as 'Authorization: Bearer hsh_...'. Query-string keys are not accepted. If the key was working before, check for whitespace introduced by a copy-paste and confirm you are calling https://headershield.dev, not a staging host.
QUOTA_EXCEEDED means your monthly scan allowance is spent — it resets at the start of the next calendar month, or upgrade on /pricing. RATE_LIMITED is the per-second burst guard: back off for the Retry-After interval (1s) and retry. Key-less surfaces (demo, badge, share) use a per-IP limiter instead — spread requests out or use your API key.
The public demo is protected by bot detection and is for humans in a browser. Scripts, curl and headless browsers are intentionally rejected with BOT_DETECTED. For automation, use the real API with a free key: GET /api/v1/scan with your X-API-Key header — that path is built for machines.
Three common causes: (1) the target resolves to a private/internal address — HeaderShield refuses to scan loopback, LAN and cloud-metadata ranges by design (SSRF protection); (2) the site blocks our fetcher (user-agent HeaderShieldBot/1.0) or times out beyond 10s — allowlist the bot or test a lighter URL; (3) a typo — the scanner needs a public hostname, and bare domains are normalised to https://.
We grade what a real browser receives at the exact URL after redirects, which includes anything your CDN or proxy adds or strips. Cloudflare, Vercel, Netlify and friends often inject defaults (or remove Server headers) so the edge response can differ from your origin config. Scan the final production hostname, compare with curl -sI through the CDN, and remember the DNS posture 'unknown' status just means the lookup timed out — re-run the scan.

Still stuck? Check the API documentation or the OpenAPI spec.

HeaderShield

Scan any site in seconds - CSP, HSTS, clickjacking, cookie flags and TLS expiry graded A+ to F, with copy-paste fixes for next.config.ts and vercel.json. One lifetime key, no per-credit pricing.

Product
  • Features
  • Pricing
  • API Docs
  • Help
  • Redeem coupon
Company
  • Privacy
  • Terms
  • Support
© 2026 HeaderShield. Security headers grading and TLS expiry monitoring for developers.