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

# Authentication

> Authenticate your API requests

The Animam API supports multiple authentication methods.

## Bearer Token (recommended)

Use an API token in the `Authorization` header:

```bash theme={null}
curl https://api.animam.ai/tenants/{slug}/corpus \
  -H "Authorization: Bearer ak_your_token"
```

### Creating a token

1. Go to **Dashboard > API Tokens**
2. Click **Create token**
3. Give it a descriptive name
4. Select the required scopes
5. Copy the token (displayed only once)

<Warning>
  Tokens are only displayed once at creation. Store them securely.
</Warning>

## Scopes

Each token has specific permissions:

| Scope                | Description          |
| -------------------- | -------------------- |
| `corpus:read`        | Read corpus          |
| `corpus:write`       | Modify corpus        |
| `conversations:read` | View conversations   |
| `settings:read`      | Read tenant settings |
| `settings:write`     | Modify settings      |
| `tokens:read`        | List tokens          |
| `tokens:write`       | Create/delete tokens |
| `*`                  | Full access          |

### Example

A token with `corpus:read` can read the corpus but not modify it:

```bash theme={null}
# OK
curl https://api.animam.ai/tenants/{slug}/corpus \
  -H "Authorization: Bearer ak_corpus_readonly"

# 403 Forbidden
curl -X POST https://api.animam.ai/tenants/{slug}/corpus \
  -H "Authorization: Bearer ak_corpus_readonly" \
  -d '{"title": "Test"}'
```

## Session Cookie (Dashboard)

For the web dashboard only. Not usable for external API.

```
Cookie: animam_session=...
```

## Legacy API Key

For backward compatibility with older integrations:

```bash theme={null}
curl https://api.animam.ai/tenants/{slug}/corpus \
  -H "X-API-Key: your_old_key"
```

<Note>
  Legacy API Keys have full access. Migrate to Bearer tokens for finer control.
</Note>

## Authentication errors

| Code | Message         | Solution                 |
| ---- | --------------- | ------------------------ |
| 401  | `Unauthorized`  | Missing or invalid token |
| 403  | `Forbidden`     | Insufficient scope       |
| 403  | `Token expired` | Create a new token       |

```json theme={null}
{
  "error": "Missing required scope: corpus:write"
}
```

## Best practices

1. **One token per integration** - Easier revocation
2. **Minimal scopes** - Principle of least privilege
3. **Regular rotation** - Change tokens periodically
4. **Environment variables** - Never commit tokens

```bash theme={null}
# .env
ANIMAM_API_TOKEN=ak_...

# Code
const token = process.env.ANIMAM_API_TOKEN
```