# Authentication and API keys

Create, store, restrict and rotate API keys safely

Canonical: https://alef-bot.top/en/developers/guides/authentication

Updated: 2026-07-13

## Create a key

The protected dashboard is the only place to manage keys. Open [API key settings](/dashboard?modal=settings&tab=public-api), choose Test or Live mode and grant only the permissions you need

> **Protect the secret.** The key is displayed only once. Never store it in browser code, URLs, analytics events, logs or source code

## Send the key

Send the key in each request with `Authorization: Bearer <api-key>`. Requests without a valid key return a stable JSON error envelope

### cURL

```bash
curl https://alef-bot.top/api/v1/account \
  --header "Authorization: Bearer $ALEFBOT_API_KEY" \
  --header "Accept: application/json"
```

### JavaScript

```javascript
const response = await fetch("https://alef-bot.top/api/v1/account", {
  headers: {
    Authorization: `Bearer ${process.env.ALEFBOT_API_KEY}`,
    Accept: "application/json",
  },
});

if (!response.ok) throw new Error(`AlefBot request failed: ${response.status}`);
const account = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    "https://alef-bot.top/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['ALEFBOT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
account = response.json()
```

## Permissions and key rotation

- Use read_only for tracking and reports only
- Use full_access only in systems that upload media or create jobs
- Create a replacement key, deploy it, confirm it is in use, then revoke the old key

## Machine-readable sources

- [OpenAPI JSON](https://alef-bot.top/api/v1/openapi.json)

- [OpenAPI YAML](https://alef-bot.top/api/v1/openapi.yaml)

- [Arazzo workflow](https://alef-bot.top/api/v1/workflows/transcribe.arazzo.yaml)