Começando

Autenticação

Duas credenciais servem a superfície /v1: API key no header X-API-Key (o caminho comum) e Bearer token OAuth 2.1 para integrações que preferem tokens de curta duração.

API key

Crie e gerencie chaves no painel (Chaves de API). A chave completa aparece uma única vez, na criação — depois só o prefixo fica visível. Envie-a em toda chamada:

curl https://api.finanseed.com.br/v1/regras \
  -H "X-API-Key: fs_live_SUA_CHAVE"

Prefixo	Ambiente
fs_live_	Produção. Chamadas contam na cota do plano e são faturáveis.
fs_test_	Sandbox. Não fatura e não consome cota — cortesia de 1.000 chamadas/mês por conta, para desenvolvimento e homologação. Mesmo contrato, mesmas regras, mesma resposta.

Ciclo de vida da chave

Expiração — opcional, escolhida na criação e imutável. Chave vencida responde 401 com o motivo; o remédio é criar outra ou rotacionar.
Rotação — gera uma chave nova herdando o tempo de vida; a anterior continua válida por uma janela de graça de 24 h, para você trocar o segredo nas suas instâncias sem downtime.
Revogação — corta na hora, inclusive dentro da janela de graça de uma rotação. Use ao menor sinal de exposição.

Guarde a chave em cofre de segredos e injete por variável de ambiente. Nunca a versione em repositório, nunca a use em código de navegador — o header X-API-Key é de servidor para servidor.

Bearer token (OAuth 2.1)

Alternativa para quem prefere credencial de curta duração: um JWT RS256 emitido pelo Authorization Server da plataforma, enviado em Authorization: Bearer <token>. O token carrega a conta (org) e os escopos (scope); o motor o valida localmente e respeita revogação imediata. Tokens expiram em 10 minutos — o fluxo de refresh_token rotaciona a cada uso. Integrações máquina-a-máquina normalmente ficam melhor servidas pela API key; fale com a gente se o seu caso pedir OAuth.

O que o gate verifica, em ordem

Passo	Falha correspondente
1 · autenticação	Credencial ausente → `401`. Chave desconhecida, revogada ou conta inativa → `403`. Chave vencida ou token inválido/expirado/revogado → `401`. Infra de autenticação fora → `503`(nunca "deixa passar").
2 · escopo	A rota exige o escopo correspondente (`calculate:write`, `regras:read`, `changelog:read`, `usage:read`). API key carrega a superfície inteira; em JWT vale o claim `scope`. Sem o escopo → `403`.
3 · rate limit	Janela por minuto, por conta, no limite do plano → `429` com `Retry-After` em segundos.
4 · cota do ciclo	Status da assinatura e teto de excedente → `402` quando o remédio é comercial (assinatura suspensa, teto atingido, cortesia de sandbox esgotada).

Detalhes de cada resposta de erro em Erros e limites.