Autenticação e chaves
Toda requisição à API pública e ao MCP é autenticada com um token de acesso pessoal. Os tokens são gerados, recebem escopos e são revogados em /account/api-keys.
Enviando o token
Use o cabeçalho HTTP padrão Authorization:
Authorization: Bearer ant_live_aB3xQ9k…Clientes que não conseguem definir Authorization (alguns gateways MCP, como o Smithery, o reservam) podem enviar o token puro em X-API-Key: ant_live_…. Se os dois estiverem presentes, vale o Authorization.
Tokens são strings aleatórias opacas — nunca os coloque em uma URL ou query string. A Anthra registra apenas os 12 primeiros caracteres de qualquer token (o prefixo visível no painel).
Formato do token
Os tokens sempre começam com o prefixo ant_live_. Eles têm ~50 caracteres de entropia em base64 segura para URL e só são mostrados a você no momento da criação. A Anthra guarda o hash sha256; se perder o token, você precisa gerar um novo.
Escopos
Escolha o menor conjunto de escopos que resolve o trabalho. Uma chave vazada com books:read não consegue, por exemplo, rodar geração nem publicar nada.
| Escopo | Permite |
|---|---|
books:read | Listar, ler e exportar seus livros e capítulos. |
books:write | Criar, atualizar, excluir e esboçar livros e capítulos. |
generation:run | Rodar o pipeline de geração com IA — esboçar, escrever, reescrever, narrar. Consome tokens e créditos da ElevenLabs. |
publish:write | Publicar ou despublicar livros e mudar a visibilidade para leitores. |
account:read | Ler o perfil da conta e o uso de tokens. |
analytics:read | Ler análises de leitores por capítulo dos seus livros publicados. |
Expiração e revogação
As chaves podem ser criadas com uma expiração opcional (1–3650 dias). Revogue uma chave a qualquer momento em /account/api-keys; as requisições seguintes com ela retornam 401 invalid_token em poucos segundos.
Alternativa por cookie de sessão
Se uma requisição para /api/v1/* chegar sem bearer token, mas com um cookie de sessão autenticado do Auth.js, a Anthra trata quem chama como o usuário conectado, com todos os escopos. Isso permite que a interface do estúdio use a própria API pública durante o desenvolvimento local sem gerar um token; integrações em produção devem sempre usar um Bearer token para que os escopos valham.
Guardando tokens com segurança
- Use variáveis de ambiente (
ANTHRA_TOKEN), um gerenciador de segredos ou.env.localno desenvolvimento local — nunca faça commit de um token. - Troque os tokens periodicamente e revogue os que não usa.
- Crie um token por integração (assim, revogar um não derruba os outros).