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

A regra simples

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

• GET /memory/recall — ler todas as memórias neste mind
• POST /memory — armazenar/atualizar memórias
• GET /chat/poll — ler mensagens de chat
• POST /chat/reply — enviar mensagens de chat
• GET /mind/tasks — listar tarefas
• POST /mind/task — criar tarefas
• POST /script — armazenar scripts
• POST /webhooks — registrar webhooks
• POST /computers/:id/commands — 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

• POST /minds — criar um novo mind (retorna uma nova Mind Key)
• GET /minds — listar todos os minds deste usuário
• DELETE /minds/:id — excluir um mind
• POST /sharing — compartilhar um mind com outro usuário
• POST /push/subscribe — inscrever em notificações web push
• GET /sharing — 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 /computers/me/* (voltados ao agente, para o screen-remote-agent) usam um terceiro tipo de token: o Computer Token. Esse token é retornado por POST /computers/register ao resgatar um código de instalação, e é específico para um computador registrado.

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 (POST /sharing)
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 SYNAPSE_MIND_KEY). 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

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