# Mind Key vs JWT — qual usar quando?
SUMMARY: Guia de decisão: Mind Key para acesso a dados do agente, JWT para gerenciamento de conta.

KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).

Mind Key vs JWT — qual usar quando?
O Synapse tem dois tokens de autenticação. Escolher o errado leva a erros 401.
Este guia oferece uma estrutura clara de decisão.
Tabela de decisão rápida
| Você quer... | Use |
|--------------|-----|
| Armazenar / recuperar memórias | Mind Key |
| Enviar / fazer poll de mensagens de chat | Mind Key |
| Gerenciar tarefas | Mind Key |
| Armazenar scripts | Mind Key |
| Registrar webhooks | Mind Key |
| Controlar computadores | Mind Key (lado do usuário) / Computer Token (lado do agente) |
| Registrar uma conta de usuário | Nenhum (público) |
| Fazer login | Nenhum (público) |
| Criar / listar / excluir minds | JWT |
| Compartilhar um mind com outro usuário | JWT |
| Inscrever-se em notificações web push | JWT |
| Ver log de auditoria | Mind Key |
A regra simples
> [!TIP]
> Se toca os dados de um único mind → Mind Key.
> Se gerencia a conta ou metadados de mind → JWT.
Mind Key — token de acesso a dados
Uma Mind Key concede acesso aos dados de um mind. É um token de longa
duração que nunca expira (até o mind ser excluído). Perfeita para:
- Agentes LLM persistindo memórias entre sessões
- Cron jobs em background
- Configuração de servidor MCP
- Integrações de webhook
- Apps mobile lendo memória
O que a Mind Key pode fazer
-  — ler todas as memórias neste mind
-  — armazenar/atualizar memórias
-  — ler mensagens de chat
-  — enviar mensagens de chat
-  — listar tarefas
-  — criar tarefas
-  — armazenar scripts
-  — registrar webhooks
-  — enfileirar comandos de computador
O que a Mind Key NÃO pode fazer
- Criar / listar / excluir minds (precisa de JWT)
- Compartilhar mind com outro usuário (precisa de JWT)
- Ver informações da conta do usuário (precisa de JWT)
- Inscrever-se em web push (precisa de JWT)
JWT — token de gerenciamento de conta
Um JWT autentica a conta do usuário. Ele expira após 7 dias e é usado para
operações em nível de conta que abrangem múltiplos minds ou envolvem outros
usuários.
O que o JWT pode fazer
-  — criar um novo mind (retorna uma nova Mind Key)
-  — listar todos os minds deste usuário
-  — excluir um mind
-  — compartilhar um mind com outro usuário
-  — inscrever em notificações web push
-  — listar compartilhamentos de mind
O que o JWT NÃO pode fazer
- Ler / escrever memórias (precisa de Mind Key)
- Enviar mensagens de chat (precisa de Mind Key)
- Gerenciar tarefas (precisa de Mind Key)
- Registrar webhooks (precisa de Mind Key)
Caso especial: Computer Token
Os endpoints  (voltados ao agente, para o screen-remote-agent)
usam um terceiro tipo de token: o Computer Token. Esse token é retornado por
 ao resgatar um código de instalação, e é específico
para um computador registrado.
| Endpoint | Auth |
|----------|------|
|  | Computer Token |
|  | Computer Token |
|  | Mind Key ou JWT |
|  | Mind Key ou JWT |
Padrões comuns
Padrão 1: agente LLM único
1. Registre uma vez → obtenha JWT
2. Crie um mind → obtenha Mind Key
3. LLM usa a Mind Key para tudo
Padrão 2: agente multi-projeto
1. Registre uma vez → obtenha JWT
2. Crie múltiplos minds (work, personal, project-x) → obtenha múltiplas Mind Keys
3. LLM carrega Mind Key diferente com base no contexto
Padrão 3: compartilhamento em equipe
1. Usuário A cria um mind → obtém Mind Key A
2. Usuário A compartilha com Usuário B via JWT ()
3. Usuário B agora pode acessar via seu próprio JWT
4. Para acesso LLM, Usuário B precisa criar sua própria Mind Key (ou usar a de A)
Padrão 4: servidor MCP
Servidores MCP sempre usam Mind Key (definida via variável de ambiente
). Uma instância de servidor MCP = um mind. Para acesso
multi-mind, rode múltiplas instâncias MCP ou implemente troca de mind no cliente.
Tabela de formato de tokens
| Token | Formato | Exemplo |
|-------|---------|---------|
| Mind Key |  + 36 chars |  |
| JWT |  + base64 |  |
| Computer Token |  + 36 chars |  |
Próximos passos
- Autenticação — guia completo de auth
- API de Usuário e Minds — endpoints protegidos por JWT
- API de Memória — endpoints protegidos por Mind Key