API Reference
Authentication
API keys, environments, scopes, and identity checks
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, event, package, and /me reads |
intake:sessions:create | POST /api/v1/sessions |
privacy:erase | DELETE /api/v1/documents/\{docId\} |
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.
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"
}