Authentication

Send API keys as Bearer tokens:

Authorization: Bearer sk_test_your_api_key

API keys are generated in the dashboard Developer settings. The plaintext key is shown once and stored by Klarefi only as a hash.

Environments

Key prefixes select the environment:

Prefix	Environment	Use for
`sk_test_`	`test`	Development and integration UAT
`sk_live_`	`live`	Production traffic

Live keys work once the workspace has an active pilot or contract, has accepted the current legal terms, and is within its live usage limits. A workspace without a pilot gets 402 billing_error, and live use starts with a 15-minute pilot call. The other gates return 402 billing_error or 428 precondition_error. Test keys are never gated.

Scopes

Keys carry scopes. The public v1 scopes are:

Scope	Allows
`cases:process`	`POST /api/v1/process`
`cases:read`	Case, workspace, command, package, event, and `/me` reads
`cases:review`	Operator queue and intake-review command submission
`connectors:read`	Connector list and detail reads
`connectors:write`	Connector create, import, and delete
`intake:sessions:create`	`POST /api/v1/sessions`
`privacy:erase`	`DELETE /api/v1/documents/\{docId\}`
`workflows:read`	`GET /api/v1/workflows`
`workflows:write`	Save workflow drafts with `POST /api/v1/workflows`
`webhooks:test`	`POST /api/v1/webhooks/test`
`webhooks:acknowledge`	Webhook delivery acknowledgements

Missing or invalid keys return 401 authentication_error. Valid keys without the required scope return 403 authorization_error.

Test keys silently drop privacy:erase before authorization, even if the stored key includes it. The default test scope set includes cases:process, cases:read, connectors:read, connectors:write, intake:sessions:create, and webhooks:test; it excludes webhooks:acknowledge.

Rotating keys

Rotate a key from Settings → Developers. Klarefi creates a replacement with the same environment and scopes, shows the new secret once, and keeps the old key valid for a 24-hour grace period. Update every client during that window. After the grace period the old key expires and returns 401 invalid_api_key.

Identify the key

curl "$KLAREFI_API_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $KLAREFI_API_KEY"

{
  "org_id": "org_abc123",
  "environment": "test"
}

Health check

GET /api/v1/health does not require authentication.

curl "$KLAREFI_API_BASE_URL/api/v1/health"

{
  "status": "ok"
}