Authentication
API keys, environments, scopes, and identity checks
API base URL
Use
https://www.klarefi.com, or the direct regional Convex HTTP URL shown in Settings → Developer.
Send API keys as Bearer tokens:
Authorization: Bearer sk_test_your_api_keyAPI 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 can be gated by billing, legal acceptance, and live usage limits.
Those gates return 402 billing_error or 428 precondition_error.
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 → Developer. 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"
}