Autenticação e limites

Chaves de API, planos, limites por minuto e por mês, cabeçalhos X-RateLimit e o token administrativo.

Chave de API

Envie a chave no cabeçalho Authorization:

Authorization: Bearer vg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Formato: vg_live_ seguido de 32 caracteres. Chave em formato inválido → 401 unauthorized.
Crie a sua em sua conta: crie a conta (e-mail e senha) ou entre, e use Gerar chave. São até 5 chaves ativas por conta; revogue as que não usar mais.
A chave em claro é exibida uma única vez, na criação; o servidor guarda só o SHA-256 e um prefixo de 8 caracteres.
Chaves criadas na conta usam o plano da conta e somam na mesma cota mensal das conexões do ChatGPT e do claude.ai feitas com ela. Chaves emitidas à mão (bun run create-key <nome> [--plano pro], para quem opera a própria instância) têm plano e cota próprios.
Chave desativada → 401 unauthorized com a mensagem "Chave de API desconhecida ou desativada."
Só no servidor MCP (/mcp), a chave também é aceita na URL, em ?key=vg_live_…, porque os conectores do claude.ai não enviam cabeçalhos. O cabeçalho, quando presente, tem prioridade. As rotas /v1/* só aceitam o cabeçalho.

O que exige chave

Rotas	Sem chave	Com chave
`/v1/diplomas`, `/v1/dispositivos`, `/v1/sumulas`, `/v1/busca`, `/v1/alteracoes`	Sim, 30 req/min por IP	Limites do plano
`/v1/resolver`, `/v1/parse`, `/v1/resolver-texto`	Não: `401 unauthorized`	Limites do plano
`/mcp` (ferramentas de leitura)	Sim, 30 req/min por IP	Limites do plano
`/mcp` (`verificar_texto`, `verificar_citacoes`, `extrair_citacoes`)	Não: erro da ferramenta	Limites do plano
`/v1/health`	Sim, público, fora dos limites	Não se aplica
`/v1/admin/*`	Não	Só com `ADMIN_TOKEN`

Planos

Plano	Por minuto	Por mês
`free`	20	1.000
`pro`	300	50.000

O limite mensal conta requisições do mês corrente (UTC) em todas as rotas autenticadas com a chave. O limite por minuto usa janela fixa de 60 segundos. Preços, o que conta como requisição e como assinar o Pro estão em Planos.

Cabeçalhos de rate limit

Toda resposta (anônima ou autenticada) traz:

Cabeçalho	Significado
`X-RateLimit-Limit`	Requisições permitidas na janela de 1 minuto
`X-RateLimit-Remaining`	Quantas ainda cabem nesta janela
`X-RateLimit-Reset`	Instante (Unix, segundos) em que a janela zera
`X-Request-Id`	Identificador da requisição (aceito na entrada; útil em suporte)

Com chave, também:

Cabeçalho	Significado
`X-RateLimit-Limit-Month`	Cota mensal do plano
`X-RateLimit-Remaining-Month`	Quanto resta da cota mensal

Quando o limite estoura

429 com error.code = "rate_limited", Retry-After em segundos e details dizendo qual janela:

{
  "error": {
    "code": "rate_limited",
    "message": "Limite de requisições sem chave atingido (30 por minuto por IP). Use uma chave de API.",
    "details": { "limite": 30, "janela": "1m" }
  }
}

Recomendação: respeite Retry-After; para o limite mensal ("janela": "mes") não adianta repetir: troque de plano ou espere o próximo mês.

Token administrativo

ADMIN_TOKEN (configurado no servidor) também vai em Authorization: Bearer …. Libera GET /v1/admin/ingest-runs e ignora todos os limites. Não o use em clientes.

Boas práticas

Faça a verificação no servidor; nunca exponha a chave no navegador ou em apps móveis. (A API aceita chamadas de qualquer origem (CORS aberto) para facilitar testes, como o "Try it" desta documentação; isso não torna seguro embutir a chave em código cliente.)
Agrupe citações: /v1/resolver aceita até 100 por chamada e conta como uma requisição.
Guarde X-Request-Id nos seus logs para correlacionar com os nossos.
Antes de enviar petições ou respostas de LLM, leia Dados e privacidade: o que a API guarda (nada do texto), o que loga e onde processa.