# Autenticação e Mind Keys
SUMMARY: Como funciona a autenticação do Synapse: Mind Keys para agentes, JWTs para humanos, ?key= para ferramentas somente-URL.

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, 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 | Nenhum (header) / 60 min (query) | Nunca |
| JWT | Interface humana, operações de conta | Nenhum | 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 (para ferramentas somente-URL)
[CODE BLOCK]
> [!WARNING]
> O parâmetro de consulta  é limitado a 60 requisições por minuto.
> O cabeçalho Bearer não tem limite de taxa. Use o cabeçalho sempre que seu
> cliente suportar cabeçalhos personalizados.
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) | Nenhum | Por mind |
| Mind Key (?key=) | 60/min | Por IP |
| JWT (header) | Nenhum | 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