# Autenticação e segurança

A API possui duas credenciais com alcances diferentes. Ambas são credenciais
bearer: quem obtiver o valor recebe as permissões correspondentes.

## Escolha antes de integrar

| Cenário | Credencial no navegador | Integração recomendada |
|---|---|---|
| Cliente administra somente a própria instância | `token` da instância | frontend chama a API da instância |
| Painel privado cujos usuários administram o servidor inteiro | `admintoken`, com exposição aceita explicitamente | frontend chama a API administrativa |
| SaaS multi-tenant ou painel entregue a clientes | Nenhuma credencial da API | frontend chama o backend; backend chama a API |

Tudo que chega ao navegador pode ser lido pelo usuário, DevTools, extensões e
scripts executados na página. Variáveis `NEXT_PUBLIC_*`, `VITE_*` e similares
não protegem segredos.

## `token` da instância

O header `token` autoriza operações de uma única instância: conexão, mensagens, chats, grupos, contatos, webhooks e demais recursos associados àquele número.

```http
token: INSTANCE_TOKEN
```

O token pode ser usado diretamente em um dashboard no navegador quando o
usuário autenticado é o dono daquela instância e já pode executar todas as
operações dela. O backend do seu SaaS deve validar o tenant antes de entregar o
token; não confie apenas no estado da interface.

Prefira manter o token em memória durante a sessão. Não o coloque no bundle,
em código versionado, logs ou analytics. Persistir em `localStorage` aumenta o
impacto de XSS e extensões maliciosas.

## `admintoken`

O header `admintoken` administra o servidor e todas as instâncias. Ele permite operações como criar/listar instâncias, atualizar campos administrativos e rotacionar credenciais.

```http
admintoken: ADMIN_TOKEN
```

Por padrão, mantenha o `admintoken` no backend. Um painel administrativo pode
usá-lo diretamente no navegador somente quando **todo usuário desse painel já
é administrador do servidor inteiro** e a exposição do token é uma decisão
aceita explicitamente.

Nunca use esse modo em SaaS multi-tenant, painel entregue a clientes,
dispositivo compartilhado ou aplicação com scripts de terceiros. Nesses casos,
a interface chama o backend do SaaS, que valida usuário, tenant e permissão
antes de usar a credencial.

## SSE

O endpoint `/sse` aceita o token da instância na query string porque a API nativa `EventSource` não permite definir headers arbitrários:

```text
/sse?token=INSTANCE_TOKEN&events=chats,messages
```

URLs podem aparecer em logs, histórico e ferramentas de observabilidade. Use HTTPS, evite registrar a query completa e prefira um proxy autenticado do seu backend quando o stream for aberto pelo navegador.

## Armazenamento e rotação

- Armazene credenciais criptografadas ou em um secret manager.
- Não use `NEXT_PUBLIC_*`, `VITE_*` ou equivalentes para tokens.
- Redija `token`, `admintoken` e URLs SSE antes de registrar requests.
- Rotacione o token de instância por `POST /instance/token/rotate` quando houver exposição.
- Rotacione o token administrativo por `POST /admin/token/rotate` seguindo o intervalo aceito pela API.
- Depois da rotação, atualize consumidores e invalide caches imediatamente.

## Matriz rápida

| Operação | Credencial |
|---|---|
| Criar e listar instâncias | `admintoken` |
| Enviar mensagens | `token` |
| Consultar chats e contatos | `token` |
| Webhook por instância | `token` |
| Webhook global | `admintoken` |
| Administração do servidor | `admintoken` |

O OpenAPI é a fonte final para a segurança de cada rota; uma operação pode sobrescrever o requisito global.