Authentication

Pass your key on every request:

Authorization: Bearer <CHITMARK_API_KEY>

Servers

env alone selects the base URL. Overrides, in precedence order: the SDK baseUrl option > CHITMARK_BASE_URL (read by both SDKs) > the env default.

Where to call from

Call the API from your backend, never from a browser: the API sends no cross-origin headers, so browser reads are blocked by default, and your secret key must never ship to clients. If a page needs a verdict, have your backend verify and pass the result down.

Idempotency

POST /v1/verify accepts optional Idempotency-Key header (or idempotencyKey in the body) so retries produce one verdict per action attempt. If both are sent, the header takes precedence; official SDKs set both to the same value. An empty header falls back to the body value. 409 idempotency_conflict means the key is already associated with a different payload fingerprint (action, session, surface, subject, context): do not reuse the key; generate a new one for the new request.

Public JWKS

GET /.well-known/jwks.json is unauthenticated and used to verify verdictToken JWTs (ES256). Respect Cache-Control and, when present, ETag / Last-Modified via conditional requests. Refresh on unknown kid. Do not fetch on every verification. Empty key set: fail closed. Never skip signature checks when JWKS is down.