Authentication

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
`segments:read`	Read segments
`segments:write`	Modify segments
`corpus:read`	Read corpus
`corpus:write`	Modify corpus
`tools:read`	Read tools
`tools:write`	Modify tools
`visitors:read`	Read visitors
`visitors:write`	Modify visitors
`conversations:read`	View conversations
`conversations:write`	Modify conversations
`settings:read`	Read tenant settings
`settings:write`	Modify settings
`billing:read`	Read billing
`stats:read`	Read analytics
`*`	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"}'

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
401	`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

API Reference

Endpoints

Bearer Token (recommended)

Creating a token

Scopes

Example

Legacy API Key

Authentication errors

Best practices

​Bearer Token (recommended)

​Creating a token

​Scopes

​Example

​Session Cookie (Dashboard)

​Legacy API Key

​Authentication errors

​Best practices

Bearer Token (recommended)

Creating a token

Scopes

Example

Session Cookie (Dashboard)

Legacy API Key

Authentication errors

Best practices