# Autenticação e Mind Keys
SUMMARY: Como funciona a autenticação do Synapse: Mind Keys para agentes, JWTs para humanos, ?key= desabilitado por padrão (somente Bearer, AUTH_QUERY_KEY_MODE=deny).

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx (?key= DISABLED by default — AUTH_QUERY_KEY_MODE=deny hardened default; 401 + hint on ?key=)
JWT: Authorization: Bearer eyJ... (120 req/min external IPs, unlimited internal; used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

Autenticação e Mind Keys
O Synapse usa dois métodos de autenticação, cada um otimizado para um caso de
uso diferente. Entender a diferença é essencial para construir integrações
confiáveis.
Dois métodos de auth
| Método | Caso de uso | Limite de taxa | Expiração |
|--------|-------------|----------------|-----------|
| Mind Key | Agentes LLM, ferramentas automatizadas | 120/min (Bearer externo); ?key= desabilitado por padrão (deny) | Nunca |
| JWT | Interface humana, operações de conta | 120/min (IPs externos) | 7 dias |
Mind Key (para agentes)
Uma Mind Key é um token de API com escopo de tenant. Ele autentica os dados de
um único mind (memórias, tarefas, chat, scripts, etc.). Use para:
- Agentes LLM chamando a API
- Scripts de automação em background
- Configuração do servidor MCP
- Qualquer integração de longa duração
Autenticação por cabeçalho (recomendada)
[CODE BLOCK]
Parâmetro de consulta (desabilitado por padrão)
[CODE BLOCK]
> [!WARNING]
> O parâmetro de consulta  está desabilitado pelo padrão endurecido
> : o servidor responde a  com 401 e a dica "Query-param auth (?key=) is disabled".
> Somente Bearer é o padrão seguro (SSOT: ). Somente se um operador definir
> explicitamente ,  funciona como válvula de transição com
> 60 req/min (por IP). Clientes Bearer externos obtêm 120 req/min por identidade; redes internas
> confiáveis são ilimitadas.
Criando uma Mind Key
[CODE BLOCK]
A resposta inclui  — salve-a imediatamente, ela é exibida apenas
uma vez.
Listando seus minds
[CODE BLOCK]
Excluindo um mind (irreversível!)
[CODE BLOCK]
JWT (para humanos)
JWTs autenticam a conta do usuário, não um mind específico. Use-os para:
- Registro e login de conta
- Criar / listar / excluir minds
- Compartilhar minds com outros usuários
- Gerenciamento de assinaturas Web Push
Registrar
[CODE BLOCK]
Retorna: 
Login
[CODE BLOCK]
Retorna: 
Expiração do JWT
JWTs expiram após 7 dias. Quando um JWT expira, basta chamar 
novamente para obter um novo. A Mind Key nunca expira, então integrações de
agentes existentes continuam funcionando.
Melhores práticas de segurança
> [!CRITICAL]
> - Nunca faça commit de Mind Keys no git. Use variáveis de ambiente.
> - Nunca registre Mind Keys em logs. Mascarie-as em logs ().
> - Faça rotação de keys se suspeitar de vazamento (exclua o mind, crie um novo).
> - Use um mind por projeto para limitar o raio de explosão se uma key vazar.
Padrão de variável de ambiente
[CODE BLOCK]
[CODE BLOCK]
Configuração do servidor MCP
[CODE BLOCK]
Padrão multi-mind
Cada usuário pode ter múltiplos minds. Padrões comuns:
| Nome do mind | Finalidade |
|--------------|------------|
|  | Memórias relacionadas ao trabalho |
|  | Preferências pessoais, família |
|  | Contexto de projeto específico |
|  | Progresso de aprendizado |
|  | Fallback de propósito geral |
Use Mind Keys diferentes para sessões LLM diferentes para manter contextos
isolados.
Limites de taxa
| Método de auth | Limite | Escopo |
|----------------|--------|--------|
| Mind Key (header) | 120/min de IPs externos (por identidade); ilimitado para redes internas confiáveis | Por mind |
| Mind Key (?key=, somente com allow) | 60/min | Por IP |
| JWT (header) | 120 req/min (IPs externos; ilimitado para redes internas confiáveis) | Por usuário |
| Endpoints públicos | Nenhum | Global |
Cabeçalhos de limite de taxa (, ,
) são incluídos nas respostas quando aplicável.
Próximos passos
- Mind Key vs JWT — quando usar qual
- API de Memória — o que você pode fazer com uma Mind Key
- API de Usuário — gerenciamento de conta com JWTs