Get access and identities

Where your API key, Workspace, and Principals come from: the three things every other page assumes you have.

Every request in these docs assumes an API key bound to one Workspace and a Principal ID. This page is where they come from.

Your first key and Workspace

Checkfu is in private alpha; access is by invitation. Request access; an admitted Organization receives an organization-scoped root API key and at least one Workspace. That root key is the bootstrap credential. Everything below is created with it.

A key has a role (root, admin, developer, runner, or viewer) and a scope. Organization-scoped root keys manage the Organization. Ordinary API keys are hard-bound to one Workspace, matching CMA, and cannot select another Workspace by header. The full contract is in Authentication.

Mint the keys you’ll actually ship with

Do not embed the root key in services. Create narrower keys for each system:

cURL

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-27" \
  --header "Idempotency-Key: key-backend-$(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "display_name": "backend-production",
    "role": "developer",
    "scope": { "type": "workspace", "workspace_id": "wrkspc_0123456789abcdef0123456789abcdef" },
    "rate_limit_per_minute": 600
  }'

The secret is returned on create or rotate and may be replayed by an exact keyed retry for up to 24 hours only while that exact key generation remains live. GET /v1/organizations/{organization_id}/api-keys and GET /v1/api-keys/{id} return current key metadata but never a secret. Patch, rotation, revocation, or replay expiry makes an old retry fail closed without returning the secret. Only an organization-scoped root key can list, retrieve, create, rotate, re-role, or revoke keys. Creation and rotation require an Idempotency-Key: one stable value per intended credential, a new value per intentionally distinct one.

Key management is an Organization-level surface. The Workspace a new key is bound to travels in the body’s scope, never a selector header.

Principals: the people and services your agents act for

A Principal is an identity inside a Workspace: one of your end users, or one of your services. Every Session names the Principal it runs for, so before the quickstart you need at least one:

cURL

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-27" \
  --header "Idempotency-Key: prin-vivian-$(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "external_subject_id": "[e-mail]",
    "principal_type": "person",
    "display_name": "Vivian"
  }'

• external_subject_id is your identifier for this identity: a user ID from your own database. Checkfu never authenticates your end users; your backend authenticates them and asserts the matching Principal on each request.
• principal_type is person for humans and service for machine identities (automations and installed agents execute as service Principals).

The returned prin_… is what you pass as principal when creating Sessions, and what PermissionAssignments and Budgets attach to. Create one Principal per end user. Per-user attribution, budgets, and audit all key off it.

The three variables, ready

export CHECKFU_API_KEY="..."        # from onboarding, or a key you minted above
export CHECKFU_ORGANIZATION_ID="org_…"
export CHECKFU_WORKSPACE_ID="wrkspc_…"
export CHECKFU_PRINCIPAL_ID="prin_…"

The SDK reads only the API key and optional base URL. CHECKFU_WORKSPACE_ID is used when an Organization-management or identity-administration path names the Workspace explicitly; it is never a client selector.

Continue to the quickstart.