Reference · Server API
API overview
Authentication, CORS, rate limits, and the shape of an error.
Conventions shared by every server-side endpoint.
Authentication#
| Endpoint | Authenticated by | Header |
|---|---|---|
/api/v1/collect | The public key, in the body | - |
/api/v1/verdict | The site secret | x-api-key |
/api/v1/verdict-public | The public key (identification only) | x-site-key |
/api/v1/payments | The site secret | x-api-key |
/api/v1/blocklist | The operator token | x-collect-token |
/api/v1/visits | The operator token | x-collect-token |
The public key is not a credential. It is in every page that runs the SDK. Wherever it appears, it identifies a site; it never authorises anything.
CORS#
/api/v1/collect and /api/v1/verdict-public send CORS headers so a browser can call them, limited to the site's origin allowlist.
/api/v1/verdict deliberately sends no CORS headers at all. A browser must not be able to reach it: the public key is in every page, and if this endpoint accepted it, anyone could ask us about anyone.
Error shape#
{ "error": "Unknown or missing site secret" }| Status | Meaning |
|---|---|
400 | Invalid body |
401 | Wrong or missing key |
403 | Origin not allowed |
404 | Not found |
429 | Rate limited |
503 | A component is not configured |
No caching#
Every route answers with Cache-Control: no-store.
Fail open#
If a call fails or times out, let your own request through. An external service in your critical path that fails closed makes its downtime into your downtime.