Autenticacao

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:

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

Multi-tenancy via endUserId (isolamento por usuario final) e a base de conhecimento (.brain/api/db) sao caracteristicas do projeto, nao permissoes separadas — basta usar o param endUserId em /chat ou /process.

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.

Se o projeto tem memoria por usuario ativada (apiMemoryPerUser=true), a IA mantem um perfil .md por endUserId em .brain/api/db/users/ que vira contexto automatico em chamadas futuras do mesmo usuario.

Mais sobre End Users →

Erros de autenticacao