API Reference

Programmatic access to security header analysis. Scan any website and receive detailed scores, findings, and recommendations.

Quick Start

Get up and running in three steps.

Create an account and generate an API key

Go to API Keys to generate your key. Up to 5 keys per account.

Make your first API call

Pass your API key via the X-API-Key header.

Get security analysis

Receive a JSON response with the security score, present/missing headers, and detailed findings.

curl -X POST https://sitesecurityscore.com/api/v1/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sss_your_api_key_here" \
  -d '{"url": "https://example.com"}'

Authentication

All API requests require an API key passed via the X-API-Key header. Keys use the sss_ prefix.

Header Format

X-API-Key: sss_your_api_key_here

Keep your API key secure

Never expose keys in client-side code or public repositories. If compromised, revoke immediately from the API Keys page.

Base URL

All API requests should be made to:

Production

https://sitesecurityscore.com/api/v1

Scan Website

Scan a website and receive its security header analysis, score, and findings.

POST/api/v1/scan

Requires an API key passed via the X-API-Key header.

Request Headers

Header	Type	Required	Description
X-API-Key	string	Required	Your API key
Content-Type	string	Required	application/json

Request Body

Parameter	Type	Required	Description
url	string	Required	The URL to scan (e.g. https://example.com)

Response

Returns a JSON object with the security score, header analysis, present/missing headers, and redirect chain.

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://example.com",
  "finalUrl": "https://example.com/",
  "score": 72,
  "reportTime": "2026-02-16T10:30:00.000Z",
  "headers": {
    "strict-transport-security": "max-age=63072000",
    "x-content-type-options": "nosniff",
    "x-frame-options": "DENY"
  },
  "missingHeaders": [
    "content-security-policy",
    "permissions-policy",
    "x-xss-protection"
  ],
  "redirectChain": [
    { "from": "http://example.com", "to": "https://example.com/", "status": 301 }
  ],
  "securityFindings": {
    "headerAnalysis": {
      "totalHeaders": 15,
      "presentHeaders": 10,
      "missingHeaders": 5,
      "informationDisclosure": ["server", "x-powered-by"],
      "dynamicWeights": { "..." : "..." }
    }
  },
  "_restricted": {
    "message": "CSP analysis, TLS analysis, and cookie security details available on higher-tier plans."
  }
}

Response Fields

Field	Type	Required	Description
id	string	Required	Unique scan identifier (UUID)
url	string	Required	The URL that was requested
finalUrl	string	Required	The URL after following redirects
score	number	Required	Security score from 0 to 100
reportTime	string	Required	ISO 8601 timestamp of the scan
headers	object	Required	Security headers found on the page
missingHeaders	string[]	Required	Security headers not present
redirectChain	array	Required	List of redirects followed
securityFindings	object	Required	Detailed header analysis and findings
_restricted	object	Optional	Indicates fields restricted to higher-tier plans

Create Key

Generate a new API key for your account. The full key is returned only once on creation.

POST/api/api-keys

Requires a JWT token passed as Authorization: Bearer <token>.

Request Body

Parameter	Type	Required	Description
name	string	Required	A descriptive name for the key (max 100 characters)

Response

201 Created

{
  "success": true,
  "message": "API key created successfully",
  "apiKey": {
    "id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Production Key",
    "keyPrefix": "sss_a1b2c3d4...",
    "key": "sss_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
    "createdAt": "2026-02-24T10:30:00.000Z"
  }
}

List Keys

Retrieve all API keys for the authenticated user. Keys are returned with masked prefixes.

GET/api/api-keys

Requires a JWT token passed as Authorization: Bearer <token>.

Response

200 OK

{
  "success": true,
  "apiKeys": [
    {
      "id": "65f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Production Key",
      "keyPrefix": "sss_a1b2c3d4...",
      "isActive": true,
      "lastUsedAt": "2026-02-24T12:00:00.000Z",
      "totalRequests": 142,
      "createdAt": "2026-02-20T10:30:00.000Z"
    }
  ],
  "count": 1,
  "maxKeys": 5
}

Update Key

Update the name or active status of an existing API key.

PATCH/api/api-keys/:id

Requires a JWT token passed as Authorization: Bearer <token>.

Request Body

Parameter	Type	Required	Description
name	string	Optional	New name for the key
isActive	boolean	Optional	Enable or disable the key

Response

200 OK

{
  "success": true,
  "message": "API key updated successfully",
  "apiKey": {
    "id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Renamed Key",
    "isActive": true
  }
}

Delete Key

Permanently delete an API key. This action cannot be undone. Any requests using the deleted key will immediately fail.

DELETE/api/api-keys/:id

Requires a JWT token passed as Authorization: Bearer <token>.

Response

200 OK

{
  "success": true,
  "message": "API key deleted successfully"
}

Code Examples

Ready to use examples for common languages and tools.

curl -X POST https://sitesecurityscore.com/api/v1/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sss_your_api_key_here" \
  -d '{"url": "https://example.com"}'

Error Codes

The API uses standard HTTP status codes.

Status	Name	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid URL or malformed request body
401	Unauthorized	Missing or invalid API key / JWT token
429	Too Many Requests	Rate limit or monthly quota exceeded
500	Server Error	Internal server error

401 Unauthorized

{
  "success": false,
  "message": "API key is required. Pass it via the X-API-Key header."
}

429 Too Many Requests

{
  "success": false,
  "message": "Monthly API limit reached (50 calls/month).",
  "limit": 50,
  "used": 50,
  "resetsAt": "2026-03-01T00:00:00.000Z"
}

400 Bad Request

{
  "error": "Domain not found. Please check the URL."
}

Start Building

Generate your API key and start scanning websites programmatically.

Get Your API Key

Last updated March 2026Report an issue