Authentication

Send your key

Send your API key as a bearer token in the Authorization header, or in an X-API-Key header. You can create keys on your API keys page.

curl https://api.checkanysite.com/v1/usage \
  -H "Authorization: Bearer $CHECKANYSITE_API_KEY"

A request without a key returns 401 with the code missing_api_key. An unknown, revoked or expired key returns its own code, listed on the errors page. As HTTP requires, every 401 response includes a WWW-Authenticate header that names the expected scheme:

HTTP/2 401
WWW-Authenticate: Bearer realm="checkanysite"
Content-Type: application/json; charset=utf-8

{"error": {"code": "missing_api_key", "message": "The request carries no API key.", …}}

Key format

A key starts with cas_live_, followed by 32 letters and digits and a 6-character checksum (a CRC32 of the rest). The checksum lets secret scanners, such as GitHub’s, tell a real key from a string that only looks like one, so a key pushed to a public repository can be caught. Keys created before we added the checksum keep working.

cas_live_<32 letters and digits><6-character checksum>

Call from your server

Keep keys in an environment variable or a secrets manager, never in your code or in a browser, where anyone can read them. The API is for servers and agents: it sends no CORS headers, and it answers a browser’s preflight request with 403 and the code browser_request. To show our results on a web page, call the API from your backend and pass the result on.

Access, limits and expiry

• Keys per account. An account can hold up to 5 working keys. All of them share the account’s 300 monthly credits.
• Access. A key with full access reads stored results and starts scans. A read-only key reads stored results, scans and usage, but can’t start a scan (read_only_key). Use a read-only key for anything that only shows our findings.
• Limits. You can give a key its own monthly credit limit. Once the key reaches it, its requests return key_limit_reached.
• Expiry. A key either never expires or stops working 30, 90 or 365 days after you create it. We email you 7 days before it expires, so you can rotate it in time.
• Usage emails. We email you when your monthly credits pass 80% and 100%. You can turn these emails off under Usage in your account.

Rotate a key

Rotating a key replaces it without downtime. On your API keys page, you get a new key with the same name, access and limit (and the same lifetime, if the old key expires), shown once. The old key keeps working for the grace period you choose (an hour, 24 hours or a week), then stops.

1. Rotate the key with a grace period long enough to deploy the new key; a day suits most apps.
2. Replace the old key everywhere it’s used: your secrets manager, environment or agent settings.
3. When the old key’s “last used” time stops changing, revoke it on your API keys page, or let its grace period end.

If a key leaks

Rotate the key with At once, which stops the old key immediately, or revoke it. Then review the latest requests under Usage in your account: each shows when it was made, what it asked for and its request ID. If you see requests you didn’t make, write to us at hello@checkanysite.com. We store only a SHA-256 hash of each key, never the key itself, so nobody can recover a key from us, including us.