Question 1

What do the grades mean?

Accepted Answer

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.

Question 2

Which headers do you check?

Accepted Answer

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.

Question 3

What is CSP and why is mine 'warn'?

Accepted Answer

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.

Question 4

What does the DNS & Email Security section check?

Accepted Answer

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.

Question 5

What is DMARC?

Accepted Answer

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.

Question 6

How do I redeem my licence coupon?

Accepted Answer

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.

Question 7

Where do I find my API key?

Accepted Answer

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.

Question 8

What are the plan limits?

Accepted Answer

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.

Question 9

Do failed scans count against my quota?

Accepted Answer

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.

Question 10

Can I embed a grade badge in my README?

Accepted Answer

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: publish a snapshot with the Share button on any scan result (browser-only, bot-protected) and embed /api/badge/{token}, which shows the frozen grade of that snapshot and links nicely to your public /r/{token} page.

Question 11

I get 401 UNAUTHORIZED

Accepted Answer

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.

Question 12

I get 429 — QUOTA_EXCEEDED or RATE_LIMITED

Accepted Answer

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.

Question 13

The homepage demo says automated access is blocked

Accepted Answer

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.

Question 14

The scan says the site is unreachable or blocked

Accepted Answer

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://.

Question 15

The grade seems wrong — my origin sends different headers

Accepted Answer

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.

Feature	Plan	API
Security-header scan + A+–F grade	All plans (Free: 10 scans/mo)	GET /api/v1/scan
Grade Simulator — grade pasted headers (no scan, no key)	Public — no account	POST /api/v1/simulate · /simulate
TLS certificate expiry + cookie flags	All 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 plans	GET /api/v1/scan → findings[].fixSnippet
Scheduled monitoring + alerts	Basic: 3 sites · Premium: 20 · Business: 100	POST /api/v1/monitors
Signed webhooks (scan.completed, monitor.changed)	Premium and above	PUT /api/v1/webhooks
Bulk scan (batch of domains)	Premium: 20/batch · Business: 50/batch	POST /api/v1/bulk/scan
Downloadable HTML security report	Premium and above (counts as one scan) · white-label on Business+	GET /api/v1/report
Public share page + grade badge	Free, no key needed	POST /api/share · GET /api/badge/{token}
README grade badge (live scan)	Free, no key needed	GET /api/badge?url=example.com

Help & Knowledge Hub

Quick start

Scan your first site

Get your API key

Call the API

Read the result

Automate it

Features & API map

Frequently asked questions

Troubleshooting