Autenticacao

Como autenticar suas requisicoes na API BuildShip — duas formas, mesmas garantias.

Copiar como .md

API Key

Toda chamada precisa autenticar com sua API key. Formato:

bld_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Formas de passar a chave

Opcao 1 — Header X-API-Key (recomendado)

curl https://api.buildship.com.br/api/v1/health \
  -H "X-API-Key: bld_sua_chave_aqui"

Opcao 2 — Authorization Bearer

curl https://api.buildship.com.br/api/v1/health \
  -H "Authorization: Bearer bld_sua_chave_aqui"

Ambos sao equivalentes. Escolha o que se encaixa melhor no seu cliente HTTP.

Permissoes

Cada API key tem permissoes especificas que voce define ao criar:

Permissao	O que permite
process	POST /process — enviar arquivo + prompt
chat	POST /chat — chat sem arquivo
templates	CRUD de templates
b2bSend	POST /b2b/send — endpoint hibrido
sessions	Listar/buscar sessoes
endUsers	Gerenciar usuarios finais
knowledgeBase	CRUD da base de conhecimento

Tente chamar um endpoint sem a permissao certa → resposta 403.

Boas praticas

Guardar a chave com seguranca

• NAO comite a chave no repositorio
• Use .env (ignorado no git) ou secrets manager (AWS Secrets, HashiCorp Vault)
• Em frontend: NUNCA exponha a chave — sempre proxy via backend

Rotacionar periodicamente

Crie chave nova → migre clientes → revogue antiga. Recomendado: rotacao a cada 90 dias.

Monitorar uso

No painel API B2B → Logs voce ve todas as chamadas com:

• Endpoint
• Status
• Tempo de resposta
• Custo (creditos)
• IP de origem

Multi-tenancy (End Users)

Se voce vai expor a API pra usuarios finais (B2B2C), use o campo endUserId em todas as chamadas:

{
  "message": "Ola",
  "endUserId": "user-456"
}

Isso isola sessoes/conversas por usuario e permite cobranca por uso individual.

Mais sobre End Users →

Erros de autenticacao

Status	Causa	Solucao
401	API key invalida ou ausente	Confira o header e a chave
403	Permissao negada	Adicione a permissao no painel
403 B2B_NOT_VERIFIED	Conta B2B nao verificada	Aguarde aprovacao (ate 48h)
429	Rate limit excedido	Aguarde ou faca upgrade