Skip to Content
CarbonFooterv2.0

Authentication

API keys and usage limits.

Scanning and /usage need an API key (the static issue catalog does not). There is no anonymous tier: the API identifies callers by key only and never looks at client addresses. Each key comes with its own rate limit and monthly scan allowance.

Sending a key

Authorization: Bearer <api_key>

or, for clients that cannot set Authorization:

x-api-key: <api_key>
Terminal
curl -s -X POST https://carbonfooter.nl/api/v2/scans \
  -H 'Authorization: Bearer cf_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"url": "example.com"}'

No key, no request

A request without a key, or with an unknown or revoked one, is answered with 401 UNAUTHORIZED and nothing is scanned. If you get a 401, check that the header is there and the key is still active.

Getting a key

Keys are issued by the CarbonFooter team; there is no self-service signup yet. Ask for one at [email protected]. A key is shown once, when it is issued. We store only a hash of it, so it cannot be looked up later — if you lose a key, ask for it to be revoked and replaced.

Treat a key like a password: keep it on your server, never in browser code or a public repository.

Limits

Two things are counted separately.

Default per key
Requests60 per minute
New scans1000 per calendar month (UTC)

Limits are set per key, so yours may differ — GET /api/v2/usage tells you.

What counts as a scan

Only a new scan — one that actually runs a browser — is counted.

  • A result served from cache is free. If you are out of scans you can still read every cached result.
  • A scan that fails because of a fault on our side (500, 503) is not counted.
  • A scan that fails because of the page (422, or a 504 timeout) is counted: the browser ran.
  • A request that is rejected before scanning — invalid, or over the request limit — costs no scan.

Rate-limit headers

Responses from /scans and /usage carry the state of your per-minute limit (a 401 does not, since there is no valid key to report on):

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute
X-RateLimit-RemainingRequests left in the current minute
X-RateLimit-ResetWhen the current minute ends, in Unix seconds

When you hit a limit

HTTPCodeMeaningWhat to do
429RATE_LIMITEDToo many requests this minuteWait for the number of seconds in Retry-After
402LIMIT_EXCEEDEDYour key's monthly scans are used upWait for error.details.resetsAt, or ask for a higher allowance

Checking your usage

Terminal
curl -s https://carbonfooter.nl/api/v2/usage \
  -H 'Authorization: Bearer cf_live_…'
Response
{
  "version": "2.0",
  "tier": "key",
  "key": { "prefix": "cf_live_a1b2", "label": "Acme agency" },
  "requests": { "limit": 60, "remaining": 59, "resetsAt": "2026-11-10T12:01:00.000Z" },
  "scans": {
    "limit": 1000,
    "used": 112,
    "remaining": 888,
    "period": "month",
    "resetsAt": "2026-12-01T00:00:00.000Z"
  }
}

A null limit means unlimited.

On this page