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

# Authentication and wire versions

> Authenticate server-side requests, bind them to one Workspace, pin the dated wire contract, and understand revocation boundaries.

## Bearer authentication

Send a Checkfu API key on every versioned request:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer <api-key>
Checkfu-Version: 2026-08-31
```

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:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
2026-08-31
```

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

<CardGroup cols={2}>
  <Card title="Get access" icon="key" href="/reference/access">
    Bootstrap an Organization, create a narrow key, and create a Principal.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/reference/errors">
    Handle typed authentication, policy, Budget, model, and runtime failures.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.