> ## 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.

# Get access and identities

> Bootstrap an Organization, mint Workspace-bound API keys, create Principals, and keep private-alpha access separate from capability support.

Checkfu's overall access program is in private alpha. That describes who may
receive credentials; it does not describe the maturity or live availability of
every capability.

<Note>
  Check the authenticated [capability status](/getting-started/status) for the
  feature and Workspace you plan to use. `alpha`, `preview`, `internal`,
  `hosted`, `local`, `customer_runner`, `rollout_fenced`, and `unavailable`
  answer different questions.
</Note>

<Note>
  Plain HTTP against the Checkfu API needs no private package.
  The documented path is usable as written for an admitted Workspace.
  Confirm [capability status](/getting-started/status) before making availability part of your application's contract.
</Note>

## Sign in to the Console

Your first sign-in to the [Console](https://app.checkfu.com) creates an
Organization with one `Development` Workspace. It does not issue an API key;
create keys on the Console's API keys page. If your sign-in belongs to an
Organization that already exists in Checkfu, you join it instead of creating a
new one. Checkfu is in private alpha and the public site does not link Console
sign-in yet; [request access](https://checkfu.com/#early-access) if you do not
have the Console address.

## Bootstrap credential

An Organization-scoped root API key is a bootstrap and recovery credential. A
Console sign-in does not mint one. Do not embed a root key in an application
service.

Use a root key to create narrower Workspace-bound keys for each system. Key
roles govern control-plane operations. Workspace `admin` keys can create and
revoke PermissionAssignments. A `developer` key can author Agents and
Environments and start authorized Sessions, but cannot create those grants.
Have an administrator grant the Agent `use_environment` on the selected
Environment before starting a Session with a Developer key.

Runtime access to Connections and other
PermissionAssignment-gated platform resources is governed separately through
PermissionAssignments, ActionPolicies, and ActionApprovals. An Agent-declared
Custom tool instead follows its exact Custom-tool ActionPolicy path and has no
invented PermissionAssignment requirement.

Create the idempotency key once for this issuance. If the request needs a
retry, rerun the `curl` command with the same key and unchanged body.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
CHECKFU_KEY_ISSUANCE_ID="key-backend-$(uuidgen)"
curl --request POST \
  "https://api.checkfu.com/v1/organizations/$CHECKFU_ORGANIZATION_ID/api-keys" \
  --header "Authorization: Bearer $CHECKFU_ROOT_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: $CHECKFU_KEY_ISSUANCE_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "display_name": "backend",
    "role": "developer",
    "scope": {
      "type": "workspace",
      "workspace_id": "'"$CHECKFU_WORKSPACE_ID"'"
    },
    "rate_limit_per_minute": 600
  }'
```

Creation and rotation use an `Idempotency-Key`. Reuse one key only for retries
of the same intended credential operation, and use a new value for a distinct
operation.

The create or rotate response is the secret-delivery surface. API-key list and
item reads return metadata and do not include a secret field. Store the secret
in your server-side secret manager and remove it from shell history, CI logs,
and application logs.

## Workspace binding

An ordinary API key is bound to one Workspace. Client headers cannot retarget
it to another Workspace. Organization-scoped root operations name the target
Organization or Workspace explicitly in the route or request body.

A valid resource ID from another Workspace is not read authority. Cross-
Workspace lookup is rejected without revealing the foreign resource.

## Rotation and revocation

Rotation creates a new key generation. Revocation removes authority for new
authenticated requests. A missing, unknown, or revoked key returns
`401 auth.invalid_key`.

For long-running work, key revocation is only one control. Before another
credentialed provider effect, the trusted execution path must also re-check the
live PermissionAssignment, ActionPolicy, ActionApproval, Connection,
Credential, Budget, and support prerequisites. An external effect already
submitted before revocation can remain indeterminate.

Audit the key creation, rotation, revocation, and any refused later use. Do not
treat secret deletion from your own store as proof that remote provider
credentials or in-flight effects were revoked.

## Create a Principal

A **Principal** is your Workspace-scoped identity for an end user or service.
Your backend authenticates the real user and asserts the matching Principal;
Checkfu does not authenticate your application's end users.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  "https://api.checkfu.com/v1/organizations/workspaces/$CHECKFU_WORKSPACE_ID/principals" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: principal-$(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "external_subject_id": "user-123",
    "principal_type": "person",
    "display_name": "Example user"
  }'
```

Use `person` for a human and `service` for a service identity. The same
Principal lineage feeds PermissionAssignments, Audit, Usage, and
Principal-scoped Budgets.

## Session identity

The authenticated API key identifies the calling system and supplies
Organization, Workspace, and role authority. Session creation also accepts
`acted_as` to name an explicitly delegated Principal; it does not accept an
unrestricted identity override.

For API-key Session creation, the delegated Principal must be active in the
same Workspace and have `act_as` permission on the selected Agent. If the
resolved Agent has governed Connection bindings, `acted_as` is required.
Omitting it in that case, naming an inactive or unknown Principal, or lacking
the delegation permission is refused with `403 policy.denied`.

Your backend must authenticate the application user and resolve the authorized
Principal. Do not pass through an unchecked Principal ID from the browser.
Delegation does not change the API key's Workspace or grant Connection access:
the applicable Connection permissions, policy, approval, and revocation checks
still apply.

The unsupported `principal` field remains a malformed request. Client event
payloads also cannot supply `authored_by`; authenticated server context records
the author. See [Create a Session](/reference/sessions#create-a-session) for the
current request fields.

### Capture policy is separate from delegation

An explicit `capture_policy` requires a root/admin API key authorized for the
Workspace. Omitting it uses the default with learning use disallowed.
`acted_as` does not grant permission to change capture or learning consent, and
an application should not forward an end-user-supplied capture policy unchecked.

## Environment variables used by the guides

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export CHECKFU_ROOT_API_KEY="..."
export CHECKFU_API_KEY="..."
export CHECKFU_ORGANIZATION_ID="org_…"
export CHECKFU_WORKSPACE_ID="wrkspc_…"
export CHECKFU_PRINCIPAL_ID="prin_…"
```

Keep all API keys on a trusted server. A browser or end-user device should
receive application-specific data from your backend, not a Checkfu API key.


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