> For the complete documentation index, see [llms.txt](https://docs.limephone.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limephone.io/api-reference/authentication.md).

# Authentication

Create an API key in the LimePhone dashboard under **Settings → API keys**. Keys look like `sk_live_…` and are shown **once**, at creation — store the value in a secret manager; only a prefix is displayed afterwards.

Send the key on every request:

```
Authorization: Bearer sk_live_your_key_here
```

A missing or malformed header returns `401 Unauthorized`.

## Your first request

Verify your key against the health endpoint:

{% tabs %}
{% tab title="curl" %}

```bash
curl https://dashboard.limephone.io/api/v1/health   -H "Authorization: Bearer sk_live_..."
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const res = await fetch('https://dashboard.limephone.io/api/v1/health', {
  headers: { Authorization: `Bearer ${process.env.LIMEPHONE_API_KEY}` },
});
console.log(await res.json()); // { status: 'ok', ... }
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

res = requests.get(
    "https://dashboard.limephone.io/api/v1/health",
    headers={"Authorization": f"Bearer {os.environ['LIMEPHONE_API_KEY']}"},
)
print(res.json())  # {'status': 'ok', ...}
```

{% endtab %}
{% endtabs %}

Keys can carry an optional \*\*IP allowlist\*\* — a valid key used from an address outside its list returns \`403 Forbidden\` — and can be given an expiry date at creation.

> **Keep keys server-side.** A secret key grants access to your call logs, recordings and contacts. Never embed it in a browser, mobile app or public repository. If a key leaks, revoke it in the dashboard and create a new one.

## Scopes

Each key carries a list of scopes chosen at creation, and every endpoint requires one. A key without the required scope receives `403 Forbidden` with the missing scope named in the message.

| Scope                              | Grants                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| `calls:read`                       | List calls; read call details, recordings, transcriptions, summaries, voicemail |
| `calls:write`                      | Write call outcomes (CRM write-back)                                            |
| `messages:read`                    | List and read messages                                                          |
| `messages:write`                   | Send SMS/MMS                                                                    |
| `contacts:read`                    | List and read contacts                                                          |
| `contacts:write`                   | Create, update, delete contacts                                                 |
| `phone-numbers:read`               | List and read phone numbers                                                     |
| `phone-numbers:write`              | Update phone-number settings                                                    |
| `users:read`                       | List organization members                                                       |
| `webhooks:read` / `webhooks:write` | Manage webhook subscriptions                                                    |
| `analytics:read`                   | Usage and analytics summaries                                                   |
| `devices:write`                    | Register / unregister push-notification device tokens                           |

Convenience scopes also exist: `read` (every `:read` scope), `write` (every `:write` scope), a per-resource wildcard such as `calls:*`, and `admin` (everything). Prefer the narrowest scopes that do the job.