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

# Authentication

> Authenticate API requests using Bearer tokens.

## Bearer token

All API requests require a Bearer token in the `Authorization` header.

```bash theme={null}
curl https://api.lumisreach.com/api/v1/voice/calls \
  -H "Authorization: Bearer lumisreach_your_api_key_here"
```

## Getting your API key

API keys are provisioned when your account is set up. Each key is prefixed with `lumisreach_` and should be kept secret.

<Note>
  API keys are hashed before storage. If you lose your key, you will need to generate a new one.
</Note>

## Key format

| Component | Example                               |
| --------- | ------------------------------------- |
| Prefix    | `lumisreach_`                         |
| Token     | `a1b2c3d4e5f6...` (32 hex characters) |
| Full key  | `lumisreach_a1b2c3d4e5f6...`          |

## Key scopes

Every API key is tied to one of three scopes, which controls what resources the key can see:

| Scope            | `teamId`        | Sees                                                                                                                                                                                                                          |
| ---------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User**         | null            | The user's personal resources + every team the user is a member of.                                                                                                                                                           |
| **Organization** | umbrella org id | Every resource across the umbrella, including all child sub-entities. Use for HQ engineering or internal tools.                                                                                                               |
| **Sub-entity**   | sub-entity id   | Only that sub-entity's resources (phone numbers, calls, contacts, etc.). Caller-trust reads walk up to the parent umbrella's registration. Use when issuing keys to per-location ops or a vendor managing a single workspace. |

Tenant isolation is enforced server-side on every endpoint. A sub-entity-scoped key cannot read or write across to a sibling sub-entity or up to the umbrella's private resources.

To pick the right scope:

* **One key for everything?** → organization-scoped.
* **Vendor needs to manage one location?** → sub-entity-scoped. Revoke the key without affecting the rest of the org.
* **Solo developer / single-user account?** → user-scoped.

See [Sub-entities](/concepts/sub-entities) for how to provision sub-entities and issue per-sub-entity keys.

## Security best practices

* Store API keys in environment variables, never in source code
* Rotate keys periodically — revoke the old key in Settings → API Keys, then issue a new one (plaintext is shown once at creation; we only store the SHA256 hash)
* Use separate keys for development and production
* Use the smallest scope that works — prefer sub-entity-scoped keys for per-location vendor integrations
* Monitor key usage via the account endpoint