> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.levrage.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.levrage.ai/_mcp/server.

# Authentication

> Authenticate with the Levrage API

The Levrage.AI API uses **Bearer token** authentication. All requests (except public discovery endpoints) require an API key.

## Getting Your API Key

1. Log in to the [Levrage.AI Studio](https://studio.levrage.ai)
2. Go to **Settings → Developers → API Keys**
3. Click **Generate New Key**
4. Copy and store your key securely — it's only shown once

> **Warning**
>
> Your API key grants full access to your account's agents, calls, and campaigns. Keep it secret. Never expose it in frontend code or public repositories.

## Using Your API Key

Include it in the `Authorization` header as a Bearer token:

```bash
curl -H "Authorization: Bearer lev_YOUR_API_KEY" \
     https://api.levrage.ai/v1/agents
```

### Code Examples

**`Python`**

```python Python
import requests

API_KEY = "lev_YOUR_API_KEY"
BASE_URL = "https://api.levrage.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(f"{BASE_URL}/agents", headers=headers)
print(response.json())
```

**`JavaScript`**

```javascript JavaScript
const API_KEY = "lev_YOUR_API_KEY";
const BASE_URL = "https://api.levrage.ai/v1";

const response = await fetch(`${BASE_URL}/agents`, {
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);
```

**`cURL`**

```bash cURL
curl -H "Authorization: Bearer lev_YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.levrage.ai/v1/agents
```

## Public Endpoints

These endpoints **do not require authentication**:

| Endpoint                                    | Description                 |
| ------------------------------------------- | --------------------------- |
| `GET /v1/health`                            | Service health check        |
| `GET /v1/industries`                        | List supported industries   |
| `GET /v1/industries/{industry}/agent-types` | Agent types for an industry |
| `GET /v1/voices`                            | Available TTS voices        |
| `GET /v1/voices/languages`                  | Supported languages         |

## Error Responses

| HTTP Status | Meaning                                           |
| ----------- | ------------------------------------------------- |
| `401`       | Missing or invalid API key                        |
| `403`       | API key doesn't have permission for this resource |
| `429`       | Rate limit exceeded — slow down                   |

```json
{
  "detail": "Invalid or expired API key"
}
```

## Rate Limits

| Plan       | Requests/Minute |
| ---------- | --------------- |
| Free       | 60              |
| Pro        | 300             |
| Enterprise | Custom          |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1706140800
```

## Best Practices

1. **Store keys in environment variables** — Never hardcode in source files
2. **Use server-side only** — Never call the API from browser/mobile frontend
3. **Rotate keys regularly** — Generate new keys and revoke old ones
4. **Use one key per environment** — Separate keys for dev, staging, production