Name: Security Headers API: Grade CSP, HSTS and Cookies
Brand: leadharbor
SKU: api-leadharbor-security-headers-check
Availability: InStock
Author: API Market

Mohammed Samaan

# HTTP Security Headers API

## Overview

The HTTP Security Headers API fetches a public page, reads its response headers and grades the ones that matter for security. It has one endpoint, `/v1/market/headers`, that takes a URL and runs seven weighted checks: Strict-Transport-Security (HSTS), Content-Security-Policy (CSP), frame protection (`frame-ancestors` or X-Frame-Options), X-Content-Type-Options, Referrer-Policy, Permissions-Policy, and the Secure, HttpOnly and SameSite flags of every cookie the page sets. It combines the results into a score from 0 to 100 and a letter grade, and gives plain-language advice for each check.

It is built for security and DevOps teams that want a quick header check in CI or monitoring, agencies and SEO tools that audit client sites, and developers who want to know which header to add next. The response gives the final `url`, the HTTP `status`, whether the page was served over `https`, the number of `redirects`, the `score` and `grade`, a `checks` array (each with `id`, `weight`, `status` of `pass`, `warn`, `fail` or `not_applicable`, the header `value` and `advice`), a `cookies` array with each cookie's flags, and a `disclosed` object with the Server and X-Powered-By values the site reveals. Every response also carries a `meta` object that you can ignore. The API grades which headers are present and how they are set; it is not a penetration test or a compliance certification.

## Features

*   **1 endpoint**: Pass a URL and get the score, grade, every check and the cookie list in one call.
*   **Simple input**: A full URL or a bare domain. A bare domain is treated as `https://`.
*   **Weighted checks**: CSP (25), HSTS (20), frame protection (15), cookies (15), X-Content-Type-Options (10), Referrer-Policy (10) and Permissions-Policy (5), adding up to 100.
*   **Strict CSP grading**: Wildcard, `https:`, `data:` and `unsafe-eval` sources only earn a warning, and `unsafe-inline` is ignored when a nonce, hash or `strict-dynamic` is present.
*   **HSTS threshold**: HSTS passes with a `max-age` of at least 180 days.
*   **Advice per check**: Each failing or weak check says what to add or change, for example which cookies need Secure and HttpOnly.
*   **Data source**: The API requests the page live and reads the headers and `Set-Cookie` values it returns.
*   **Rate limit**: 10 requests per second on every plan.

## Use Cases

*   **CI and deploy checks**: Fail a release when the grade drops below your target or HSTS disappears.
*   **Site audits**: Give clients a scored report of missing headers with the fix for each one.
*   **Cookie reviews**: Find session cookies that are missing Secure, HttpOnly or SameSite.
*   **Clickjacking checks**: Confirm that `frame-ancestors` or X-Frame-Options stops other sites from framing your pages.
*   **Vendor and supplier reviews**: Compare the header setup of third-party sites you depend on.
*   **Monitoring**: Re-check key pages on a schedule and alert when the score changes.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/leadharbor/security-headers-check
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Grade the security headers of a page

Fetches the page at `url` and returns its security score, letter grade, the result and advice for each check, the cookies it sets and the server details it discloses.

**Method:** `GET`

**Endpoint:** `/v1/market/headers`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | The page to check, for example `https://github.com`. A bare domain is treated as `https://`. Only public addresses are accepted. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/leadharbor/security-headers-check/v1/market/headers?url=https%3A%2F%2Fgithub.com" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "url": "https://github.com/",
  "status": 200,
  "https": true,
  "redirects": 0,
  "score": 80,
  "grade": "B",
  "checks": [
    {
      "id": "hsts",
      "weight": 20,
      "status": "pass",
      "value": "max-age=31536000; includeSubdomains; preload",
      "advice": "HSTS is set with a long max-age."
    },
    {
      "id": "csp",
      "weight": 25,
      "status": "pass",
      "value": "default-src 'none'; base-uri 'self'; child-src github.githubassets.com github.com/assets-cdn/worker/ github.com/assets/ gist.github.com/assets-cdn/worker/; connect-src 'self' uploads.github.com www.githubstatus.com collector.github.com raw.githubusercontent.com api.github.com github-cloud.s3.amazonaws.com github-production-repository-file-5c1aeb.s3.amazonaws.com github-production-upload-manifest-file-7fdce7.s3.amazonaws.com github-production-user-asset-6210df.s3.amazonaws.com *.rel.tunnels.api.visualstudio.com wss://*.rel.tunnels.api.visualstudio.com github.githubassets.com objects-origin.githubusercontent.com copilot-proxy.githubusercontent.com proxy.individual.githubcopilot.com proxy.business.githubcopilot.com proxy.enterprise.githubcopilot.com *.actions.githubusercontent.com wss://*.actions.githubusercontent.com productionresultssa0.blob.core.windows.net productionresultssa1.blob.core.windows.net productionresultssa2.blob.core.windows.net productionresultssa3.blob.core.windows.net productionresultssa4.blob.core.windows.net productionresultssa5.blob.core.windows.net productionresultssa6.blob.core.windows.net productionresultssa7.blob.core.windows.net productionresultssa8.blob.core.windows.net productionresultssa9.blob.core.windows.net productionresultssa10.blob.core.windows.net productionresultssa11.blob.core.windows.net productionresultssa12.blob.core.windows.net productionresultssa13.blob.core.windows.net productionresultssa14.blob.core.windows.net productionresultssa15.blob.core.windows.net productionresultssa16.blob.core.windows.net productionresultssa17.blob.core.windows.net productionresultssa18.blob.core.windows.net productionresultssa19.blob.core.windows.net github-production-repository-image-32fea6.s3.amazonaws.com github-production-release-asset-2e65be.s3.amazonaws.com insights.github.com wss://alive.github.com wss://alive-staging.github.com api.githubcopilot.com api.individual.githubcopilot.com api.business.githubcopilot.com api.enterprise.githubcopilot.com wss://production-copilot-host.webpubsub.azure.com api.github.com/cmc_internal/api/ edge.fullstory.com rs.fullstory.com; font-src github.githubassets.com; form-action 'self' github.com gist.github.com copilot-workspace.githubnext.com objects-origin.githubusercontent.com; frame-ancestors 'none'; frame-src viewscreen.githubusercontent.com notebooks.githubusercontent.com www.youtube-nocookie.com; img-src 'self' data: blob: github.githubassets.com media.githubusercontent.com camo.githubusercontent.com identicons.github.com avatars.githubusercontent.com private-avatars.githubusercontent.com github-cloud.s3.amazonaws.com objects.githubusercontent.com release-assets.githubusercontent.com secured-user-images.githubusercontent.com user-images.githubusercontent.com private-user-images.githubusercontent.com opengraph.githubassets.com repository-images.githubusercontent.com marketplace-screenshots.githubusercontent.com copilotprodattachments.blob.core.windows.net/github-production-copilot-attachments/ github-production-user-asset-6210df.s3.amazonaws.com customer-stories-feed.github.com spotlights-feed.github.com explore-feed.github.com *.googleusercontent.com objects-origin.githubusercontent.com *.githubusercontent.com images.ctfassets.net/8aevphvgewt8/; manifest-src 'self'; media-src github.com user-images.githubusercontent.com secured-user-images.githubusercontent.com private-user-images.githubusercontent.com github-production-user-asset-6210df.s3.amazonaws.com gist.github.com github.githubassets.com assets.ctfassets.net/8aevphvgewt8/ videos.ctfassets.net/8aevphvgewt8/; script-src github.githubassets.com 'sha256-tSjmyPUky1KbRZ0fw9VUil3wFEbeM82rtbJDygGJAXw='; style-src 'unsafe-inline' github.githubassets.com; upgrade-insecure-requests; worker-src github.githubassets.com github.com/assets-cdn/worker/ github.com/assets/ gist.github.com/assets-cdn/worker/",
      "advice": "A Content-Security-Policy restricts scripts."
    },
    {
      "id": "frame_protection",
      "weight": 15,
      "status": "pass",
      "value": "'none'",
      "advice": "Framing by other sites is restricted."
    },
    {
      "id": "content_type_options",
      "weight": 10,
      "status": "pass",
      "value": "nosniff",
      "advice": "Browsers will not guess content types."
    },
    {
      "id": "referrer_policy",
      "weight": 10,
      "status": "pass",
      "value": "origin-when-cross-origin, strict-origin-when-cross-origin",
      "advice": "Referrer-Policy is set."
    },
    {
      "id": "permissions_policy",
      "weight": 5,
      "status": "fail",
      "value": null,
      "advice": "Send Permissions-Policy to switch off browser features the page does not use, for example camera=(), microphone=()."
    },
    {
      "id": "cookies",
      "weight": 15,
      "status": "fail",
      "value": "_octo",
      "advice": "Add Secure and HttpOnly to: _octo."
    }
  ],
  "cookies": [
    {
      "name": "_gh_sess",
      "secure": true,
      "http_only": true,
      "same_site": "lax"
    },
    {
      "name": "_octo",
      "secure": true,
      "http_only": false,
      "same_site": "lax"
    },
    {
      "name": "logged_in",
      "secure": true,
      "http_only": true,
      "same_site": "lax"
    }
  ],
  "disclosed": {
    "server": "github.com",
    "x_powered_by": null
  },
  "meta": {
    "user": null
  }
}
```

In this example GitHub passes five checks and fails two: Permissions-Policy (weight 5) is not sent, and the `_octo` cookie lacks HttpOnly (weight 15), which gives a score of 80 and grade `B`. A `value` of `null` means the header was not present. `disclosed.x_powered_by` is `null` because the site does not send that header. The `meta` object is metadata you can ignore.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The page was fetched and graded. A page with weak headers still returns `200`; read `score`, `grade` and `checks`. |
| 400 | Bad Request | `url` is missing or invalid, or it points to a non-public address. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The request path is wrong. Check that it is `/v1/market/headers` under the base URL. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used all the calls in your plan. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The page could not be fetched, for example because the site is down or refused the connection. |

## Rate Limits

The Free trial, Starter and PAYG plans each allow 10 requests per second. The 7-day Free trial includes 500 calls, Starter includes 10,000 calls with extra calls at $0.001 each, and PAYG charges $0.001 per call with no subscription. Requests above the per-second limit, or after the Free trial's calls are used up, return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header, which says how many seconds to wait. Each call fetches the target page live, so response time depends on that site; in our test the GitHub check took about 0.7 seconds.

## FAQ

**How is the score calculated?**

Each check has a weight, and the weights add up to 100: CSP 25, HSTS 20, frame protection 15, cookies 15, X-Content-Type-Options 10, Referrer-Policy 10 and Permissions-Policy 5. Failing checks lose their weight, as in the GitHub example, where failing Permissions-Policy and cookies gives 80. The letter `grade` is derived from the score.

**Why did my CSP only get a warning?**

A policy that allows scripts from a wildcard, from any `https:` source, from `data:` or with `unsafe-eval` still lets attackers load scripts, so it earns `warn` instead of `pass`. `unsafe-inline` is ignored when the policy also uses a nonce, a hash or `strict-dynamic`, because browsers then ignore it too.

**Which cookies are checked?**

Every cookie the page sets in its response. Each one appears in `cookies` with its `secure`, `http_only` and `same_site` values, and the `cookies` check names the ones that are missing flags.

**What do `url` and `redirects` in the response mean?**

`url` is the address that was graded and `redirects` is the number of redirect hops before it (0 in the GitHub example). `https` says whether the final page was served over HTTPS.

**Is this a full security scan?**

No. It grades which security headers are present and how they are set. It does not test for vulnerabilities, and it is not a penetration test or a compliance certification.

**Can I check an internal or staging site?**

Only if it is reachable on a public address. Private, local and other non-public addresses return `400`, and a public site that cannot be reached returns `502`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Security headers API that grades a page's CSP, HSTS, frame protection, Referrer-Policy and cookie flags, with a score, grade and fix advice.

Security Headers API: Grade CSP, HSTS and Cookies

Free trial