# Authentication
API keys, environments, scopes, and identity checks
Source: https://www.klarefi.com/docs/api/authentication

> **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:

```http
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 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

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

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

## Health check

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

```bash
curl "$KLAREFI_API_BASE_URL/api/v1/health"
```

```json
{
  "status": "ok"
}
```