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) ```bash curl https://api.buildship.com.br/api/v1/health \ -H "X-API-Key: bld_sua_chave_aqui" ``` ### Opcao 2 — Authorization Bearer ```bash 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, /process/batch — enviar arquivo + prompt | | `chat` | POST /chat, GET /chat/:id, /chat/sessions — chat e historico | | `templates` | CRUD de templates + upload | | `b2bSend` | POST /b2b/send — endpoint hibrido | 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: ```json { "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 →](/docs/api/endpoints#end-users-multi-tenancy-via-parametro) ## 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 |