> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lehar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, bearer login sessions, scopes, and which endpoints need which.

Lehar supports two credential types on the same API. Pick based on the caller.

| Credential               | Header                    | Use from                                                   |
| ------------------------ | ------------------------- | ---------------------------------------------------------- |
| **Workspace API key**    | `X-API-KEY: lk_live_…`    | Trusted server-side code                                   |
| **Bearer login session** | `Authorization: Bearer …` | An authenticated user (dashboard, or your app after login) |

A login session may also be presented as the `myna_session` HttpOnly cookie set by `POST /auth/login`; the header wins over the cookie.

<Warning>
  **Session creation requires a bearer login session, not an API key.** `POST /sessions`
  attaches the session to the logged-in user, so an API key alone returns `400`. Everything
  else (agents, campaigns, workspace, history) accepts an API key.
</Warning>

## Scopes

API keys carry scopes. Requests without the required scope return `403`.

| Scope                            | Grants                                                             |
| -------------------------------- | ------------------------------------------------------------------ |
| `workspace:read`                 | Read workspace / customer details                                  |
| `sessions:read`                  | List/get sessions, read the agent catalog                          |
| `sessions:write`                 | Create and update sessions and agents                              |
| `api_keys:read`                  | List API keys                                                      |
| `api_keys:write`                 | Create and revoke API keys (only granting scopes you already hold) |
| `knowledge_base:read`            | Search and list knowledge-base entries                             |
| `knowledge_base:write`           | Ingest and delete knowledge-base entries                           |
| `pronunciation_dictionary:read`  | List and attach pronunciation dictionaries                         |
| `pronunciation_dictionary:write` | Create, edit, and delete pronunciation dictionaries (admins)       |
| `campaigns:read`                 | List campaigns, recipients, attempts, and events                   |
| `campaigns:write`                | Create, edit, publish, and run campaigns                           |
| `phone_numbers:read`             | List phone numbers and SIP trunks                                  |
| `phone_numbers:write`            | Manage phone-number bindings and SIP trunks                        |
| `whatsapp_numbers:read`          | List WhatsApp senders                                              |
| `whatsapp_numbers:write`         | Manage WhatsApp senders                                            |
| `analytics:read`                 | Read the analytics overview                                        |
| `billing:read`                   | Read your credit balance and ledger                                |
| `billing:write`                  | Reserved for administrative billing actions                        |

## Get a key

Create a key in the dashboard, or via the API with an existing `api_keys:write` key:

```bash theme={null}
curl -X POST "$LEHAR_BASE_URL/workspace/api-keys" \
  -H "X-API-KEY: $LEHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "backend", "scopes": ["sessions:read","sessions:write"] }'
```

The raw key is returned **once** — store it in a secrets manager.

<Note>
  You can only grant a new key scopes your current credential already holds. Requesting a
  broader scope returns `403` and creates nothing.
</Note>

## Rotate a key

1. Create a new key (above) and deploy it.
2. Revoke the old key:

```bash theme={null}
curl -X DELETE "$LEHAR_BASE_URL/workspace/api-keys/key_OLD_ID" \
  -H "X-API-KEY: $LEHAR_NEW_KEY"
```

## Security notes

* Keys are stored as hashes only and are never logged.
* Participant tokens are returned only when a session is created — never in list/get responses.
* Tenant isolation is enforced on every query by workspace.
* Key revocation takes effect immediately.