Authentication & keys
Every public API and MCP request authenticates with a personal access token. Tokens are generated, scoped, and revoked from /account/api-keys.
Presenting the token
Use the standard HTTP Authorization header:
Authorization: Bearer ant_live_aB3xQ9k…Tokens are opaque random strings — never embed them in a URL or query string. Anthra logs only the first 12 characters of any token (the visible prefix shown in the dashboard).
Token format
Tokens always start with the prefix ant_live_. They are ~50 characters of URL-safe base64 entropy and are only ever shown to you at creation time. Anthra stores the sha256 hash; lose the token and you must mint a new one.
Scopes
Pick the narrowest set of scopes that does the job. A leaked key with books:read cannot, for example, run generation or publish anything.
| Scope | Grants |
|---|---|
books:read | List, read, and export your books and chapters. |
books:write | Create, update, delete, and outline books and chapters. |
generation:run | Run the AI generation pipeline — outline, write, rewrite, narrate. Spends tokens and ElevenLabs credits. |
publish:write | Publish or unpublish books and change reader visibility. |
account:read | Read account profile and token usage. |
analytics:read | Read per-chapter reader analytics for your published books. |
Expiry & revocation
Keys can be created with an optional expiry (1–3650 days). Revoke a key at any time from /account/api-keys; subsequent requests with it return 401 invalid_token within seconds.
Cookie-session fallback
If a request to /api/v1/* arrives without a bearer token but does carry an authenticated Auth.js session cookie, Anthra treats the caller as the signed-in user with all scopes. This lets the studio UI dogfood the public API during local development without minting a token; production integrations should always use a Bearer token so scopes apply.
Storing tokens safely
- Use environment variables (
ANTHRA_TOKEN), a secret manager, or.env.localfor local development — never commit a token. - Rotate tokens periodically and revoke unused ones.
- Create one token per integration (so revoking one doesn’t kill the others).