# auth.md — autenticação de agentes no Brasahub

## Quem é o público

Agente, integração ou software de terceiro que vai ler dados de UM
estabelecimento cliente do Brasahub (pedidos, vendas e produtos), a mando do
dono daquele estabelecimento.

O Brasahub é um sistema de gestão para restaurantes, bares e lanchonetes. Não
existe dado de acesso público na API: toda chamada responde apenas pelos dados
do estabelecimento que emitiu a credencial.

## Não existe cadastro automático

Não há `register_uri`, client registration dinâmico (RFC 7591) nem servidor de
autorização OAuth. Um agente **não consegue** criar credencial sozinho, e isso
é intencional: a credencial dá acesso ao faturamento de um negócio real.

A credencial é emitida por uma pessoa com conta ativa:

1. O dono do estabelecimento entra em https://brasahub.com.br/ e assina o plano Full
   (a API pública é um recurso desse plano).
2. No sistema, vai em **Configurações → API e Webhooks**.
3. Clica em **Gerar chave**, dá um nome à chave e copia o valor.
4. Entrega a chave ao agente pelo canal que ele já usa com o cliente.

A chave aparece em texto puro uma única vez, na hora da criação. Depois disso
só é possível revogar e gerar outra.

## Método suportado

Bearer token em header, e só.

```http
GET https://fzqhxzzifujdwjtyvfjw.supabase.co/functions/v1/public-api/orders?limit=50
Authorization: Bearer bh_live_...
```

- `bearer_methods_supported`: `header`. A chave não é aceita em query string
  nem no corpo — query string vaza em log de proxy e em histórico.
- Formato da chave: prefixo `bh_live_`. Guardada como hash no servidor.
- Escopo: leitura (`read`). Não existe escrita pela API pública hoje.
- Recursos: `/orders`, `/sales`, `/products`.

## Uso da credencial

- Uma chave = um estabelecimento. Ela não enxerga dados de outro cliente do
  Brasahub, mesmo que o mesmo agente atenda vários.
- A validade é reavaliada a cada chamada: se o estabelecimento sair do plano
  Full ou o dono revogar a chave, a resposta vira `401 invalid_api_key` na
  hora, sem aviso prévio. Trate 401 como "peça uma chave nova ao cliente", não
  como falha temporária.
- Limites: 600 requisições/minuto por IP e 240/minuto por estabelecimento.
  Estouro devolve `429` com `retry_after` em segundos — respeite o valor.
- Nunca registre a chave em log, prompt ou telemetria.

## Onde continuar

- Documentação: https://brasahub.com.br/api
- Especificação OpenAPI: https://brasahub.com.br/openapi.json
- Catálogo de APIs: https://brasahub.com.br/.well-known/api-catalog
- Contato humano: suporte@brasahub.com.br