> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and versions

> Authenticate server-side requests and pin Checkfu's dated wire contract.

## Bearer authentication

Send a Checkfu API key in the `Authorization` header on every versioned request ([Get access](/reference/access) covers where keys come from):

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer <api-key>
```

API keys are server-side credentials. Do not place them in browser code or expose them to a [Principal](/concepts/tenancy-and-governance).

A missing, unknown, or revoked key returns `401 auth.invalid_key`.

## Dated wire versions

Send the required `Checkfu-Version` header alongside the key:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Checkfu-Version: 2026-08-27
```

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](/concepts/sessions-and-runs) 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](/concepts/tenancy-and-governance):

* 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

<CardGroup cols={2}>
  <Card title="Sessions" icon="layer-group" href="/reference/sessions">
    Create a Session, retrieve it by ID, and read the fields the wire contract returns.
  </Card>

  <Card title="Events" icon="list-timeline" href="/reference/events">
    Stream a Session's event log: the settlement record every authenticated request writes to.
  </Card>
</CardGroup>