The Animam API supports multiple authentication methods.
Bearer Token (recommended)
Use an API token in the Authorization header:
curl https://api.animam.ai/tenants/{slug}/corpus \
-H "Authorization: Bearer ak_your_token"
Creating a token
- Go to Dashboard > API Tokens
- Click Create token
- Give it a descriptive name
- Select the required scopes
- Copy the token (displayed only once)
Tokens are only displayed once at creation. Store them securely.
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:
# 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:
curl https://api.animam.ai/tenants/{slug}/corpus \
-H "X-API-Key: your_old_key"
Legacy API Keys have full access. Migrate to Bearer tokens for finer control.
Authentication errors
| Code | Message | Solution |
|---|
| 401 | Unauthorized | Missing or invalid token |
| 403 | Forbidden | Insufficient scope |
| 403 | Token expired | Create a new token |
{
"error": "Missing required scope: corpus:write"
}
Best practices
- One token per integration - Easier revocation
- Minimal scopes - Principle of least privilege
- Regular rotation - Change tokens periodically
- Environment variables - Never commit tokens
# .env
ANIMAM_API_TOKEN=ak_...
# Code
const token = process.env.ANIMAM_API_TOKEN
