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

# Authentication

> Every request carries an API key. Keys belong to your business and can be limited to certain actions, IP addresses and dates.

## Create a key

**1. Open API keys**

Sign in and open **Settings → API keys**. Only business admins can create keys.

**2. Name it**

Name it after the system that will use it, for example *Shop backend*.

**3. Limit it (optional)**

Choose [scopes](#scopes), [allowed IP addresses](#ip-allowlist) and an expiry date.

**4. Copy it**

The key starts with `tlv_` and is shown only once. Messaly stores a hash of it, not the key.

## Send it with every request

Use either header:

```http theme={null}
Authorization: Bearer tlv_your_api_key_here
```

```http theme={null}
X-API-Key: tlv_your_api_key_here
```

```bash cURL theme={null}
curl https://app.telaven.com/api/v1/balance \
  -H "Authorization: Bearer $TELAVEN_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch("https://app.telaven.com/api/v1/balance", {
  headers: { Authorization: `Bearer ${process.env.TELAVEN_API_KEY}` },
});
console.log(await res.json());
```

```python Python theme={null}
import os, requests

res = requests.get(
    "https://app.telaven.com/api/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['TELAVEN_API_KEY']}"},
)
print(res.json())
```

```php PHP theme={null}
<?php
$ch = curl_init("https://app.telaven.com/api/v1/balance");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer " . getenv("TELAVEN_API_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
print_r(json_decode(curl_exec($ch), true));
```

```csharp C# theme={null}
using System.Net.Http.Headers;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("TELAVEN_API_KEY"));

var json = await http.GetStringAsync("https://app.telaven.com/api/v1/balance");
Console.WriteLine(json);
```

## Scopes

A key with no scopes selected can call every endpoint. Give each system only the scopes it needs, so a leaked key can do less. A call outside the key's scopes gets `403`.

| Scope | Allows |
| - | - |
| `sms:send` | Send SMS and create, edit, schedule and send SMS campaigns |
| `sms:read` | Read SMS messages, campaigns, recipients and analytics |
| `contacts:read` | Read contacts and contact lists |
| `contacts:write` | Create, edit and delete contacts and contact lists |
| `crm:read` | Read deals, companies and pipelines |
| `crm:write` | Create deals, companies and pipelines |
| `email:read` | Read email campaigns and unsubscribes |
| `email:write` | Create and send email campaigns; manage unsubscribes |
| `wallet:read` | Read wallet balance and pricing |
| `whatsapp:send` | Send WhatsApp templates; manage templates and WhatsApp campaigns |

Each endpoint in the [API reference](https://docs.telaven.com/api-reference/account/get-balance.md) names the scope it needs.

## IP allowlist

Add your servers' public IP addresses to a key and it will be refused (`403`) from anywhere else. Leave the list empty to allow any address.

## When it goes wrong

| Status | Message | Cause |
| - | - | - |
| `401` | `Unauthorized` | Missing, wrong, disabled or expired key. |
| `403` | `this API key does not have the '…' scope` | Add the scope, or use another key. |
| `403` | `this API key cannot be used from <ip>` | Called from an address that isn't on the key's allowlist. |
| `429` | `Too many requests` | Over the key's request limit. See [Rate limits](https://docs.telaven.com/get-started/rate-limits.md). |

> [!WARNING]
>
> **Keep keys on your server.** Never put one in a mobile app, browser code or a public repository: anyone holding it can send messages billed to your wallet.
> If a key leaks, disable it in **Settings → API keys** straight away and create a new one. The page shows when each key was last used.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.