Skip to main content

​
Bearer authentication

Send a Checkfu API key in the Authorization header on every versioned request (Get access covers where keys come from):
API keys are server-side credentials. Do not place them in browser code or expose them to a Principal. A missing, unknown, or revoked key returns 401 auth.invalid_key.

​
Dated wire versions

Send the required Checkfu-Version header alongside the key:
Wire versions cover request and response shapes, event envelopes, and error contracts. They are dates rather than semantic package versions because the interface is an HTTP contract, not an SDK release. Every Session records the wire version with which it was created. During the D257 pre-launch multiagent rewrite, each contract cut requires fresh storage and serves only the current version, now 2026-08-27; older Sessions are deliberately not translated or resumed. Current errors carry the stable more remedy URL. If the header is missing or unsupported, the request returns 400 validation.malformed.

​
Workspace scope

Every accepted data-plane request resolves to exactly one Workspace:
  • An ordinary API key is hard-bound to one Workspace, matching CMA.
  • An organization-scoped root key is limited to Organization-management operations. Nested Admin routes name a Workspace explicitly in the path.
  • Checkfu-Environment, Checkfu-Workspace, and Checkfu-Workspace-Id are rejected request selectors; a request cannot override the key’s Workspace.
Session storage and lookup are resolved inside that Workspace. A valid Session ID from a different Workspace therefore returns 404 validation.not_found rather than exposing that the resource exists. Only an organization-scoped root key can list, retrieve, create, rotate, re-role, or revoke API keys. List and item reads expose metadata only, never the secret. Creation and rotation require a non-empty Idempotency-Key; use one stable value for retries of one intended credential operation and a new value for each intentionally distinct creation. An exact retry can replay the one-time secret for up to 24 hours only while that exact key generation is still live; patch, rotation, revocation, or expiry makes the replay fail closed without returning the old secret.

​
Next steps

Sessions

Create a Session, retrieve it by ID, and read the fields the wire contract returns.

Events

Stream a Session’s event log: the settlement record every authenticated request writes to.