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

# Authentication

> API keys, roles, and token limits

## API Keys

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

```bash theme={null}
Authorization: Bearer sk-YOUR_API_KEY
```

API keys start with `sk-` and are created in the [Dashboard](https://aigmented.io) under Settings → API Keys.

<Warning>
  API keys are shown only once when created. Store them securely.
</Warning>

## Required role

API access requires **Moderator** role or above in your team. Users with the basic `USER` role will receive a `403 Forbidden` response.

| Role          | API Access |
| ------------- | ---------- |
| User          | No         |
| Moderator     | Yes        |
| Administrator | Yes        |

## Token limits

Every API call consumes tokens from your team's subscription. The system enforces limits:

* **Before each request:** Token availability is checked (`enforceTokenLimit`)
* **After each request:** Actual usage is tracked and deducted

When your token limit is exceeded, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "error": "Token limit exceeded",
  "remaining": 0,
  "reason": "Monthly token quota exhausted"
}
```

## Error codes

| Status                  | Meaning                                        |
| ----------------------- | ---------------------------------------------- |
| `401 Unauthorized`      | Missing or invalid API key                     |
| `403 Forbidden`         | User role insufficient (need Moderator+)       |
| `404 Not Found`         | Collection not found or not owned by your team |
| `429 Too Many Requests` | Token limit exceeded                           |