Skip to main content

​
Bearer authentication

Send a Checkfu API key on every versioned request:
API keys are server-side credentials. Do not place them in browser code, model context, Session events, or a Principal-controlled client. A missing, unknown, revoked, or expired key returns 401 auth.invalid_key.

​
Dated wire versions

Checkfu-Version selects the request, response, event-envelope, and error contract. The current version is:
A missing or unsupported version returns 400 validation.malformed. Pin the version in one client configuration rather than adding it independently at each call site. A Session records the wire version under which it was created. Wire version is an HTTP compatibility contract; it is independent of the SDK package version and independent of capability support readiness.

​
Workspace scope

Every accepted data-plane request resolves to one Workspace:
  • an ordinary API key is bound to one Workspace;
  • an Organization-scoped root key is limited to Organization-management operations; and
  • nested administration routes name their target explicitly.
Checkfu-Environment, Checkfu-Workspace, and Checkfu-Workspace-Id are not Workspace selector headers. A caller cannot use one to override the key’s binding. A foreign resource ID does not reveal cross-Workspace existence. The lookup is resolved inside the authenticated Workspace and returns the typed not-found response when no local resource matches.

​
API-key roles and runtime governance

API-key roles govern who may create, read, update, rotate, or revoke control-plane resources. They do not replace runtime governance. For a governed provider action, Checkfu separately evaluates:
  1. PermissionAssignment;
  2. ActionPolicy;
  3. ActionApproval, when required;
  4. live Connection and Credential revocation;
  5. Budget and quota state; and
  6. capability and runtime prerequisites.
A request can therefore authenticate successfully and still receive policy.denied, budget.exceeded, or a runtime or model availability error.

​
Rotation, revocation, and in-flight work

Key-management metadata routes do not return secret bytes. Creation and rotation are the secret-delivery operations and require an idempotency key under their typed contract. When creating an Organization-managed API key, you can set expires_at to a future UTC timestamp. Omit it or use null for an unbounded key. The finite expiry appears in key metadata and remains fixed when you rotate the secret; rotation does not renew the key. Expiry does not turn the key into a Console session credential. The key’s lifetime and the one-time secret recovery window are separate. Recovery releases the same original secret only while both remain current; a retry cannot create a replacement for an expired or revoked original key. If creation or rotation returns 503 auth.authorization_unavailable, retry with the same idempotency key and request body. The error means that current authority could not be evaluated; it does not prove that the key mutation failed. A mutation may already be committed while secret delivery is withheld. Recovery returns that original issuance while its recovery window and current authority permit it. Do not switch to a new idempotency key to recover a secret. Revocation fails new authentication at the next request check. It cannot retroactively prove that an external provider effect submitted earlier did not occur. Long-running execution must re-check the live authorities at the next trusted boundary before another provider effect, and Audit records the observed disposition. When an effect is uncertain, reconcile it using the Session event log and the provider’s admitted idempotency or lookup mechanism. Do not infer absence from an authentication error that happened later.

​
Next steps

Get access

Bootstrap an Organization, create a narrow key, and create a Principal.

Errors

Handle typed authentication, policy, Budget, model, and runtime failures.