{"title":"Mind Key vs JWT — qual usar quando?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Guia de decisão: Mind Key para acesso a dados do agente, JWT para gerenciamento de conta.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":758,"read_minutes":4,"llm_context":"Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.\nJWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.\nSimple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.\nException: /computers/me/* uses Computer Token (not Mind Key or JWT).\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Mind Key vs JWT — qual usar quando?\n\nO Synapse tem dois tokens de autenticação. Escolher o errado leva a erros 401.\nEste guia oferece uma estrutura clara de decisão.\n\n## Tabela de decisão rápida\n\n| Você quer... | Use |\n|--------------|-----|\n| Armazenar / recuperar memórias | Mind Key |\n| Enviar / fazer poll de mensagens de chat | Mind Key |\n| Gerenciar tarefas | Mind Key |\n| Armazenar scripts | Mind Key |\n| Registrar webhooks | Mind Key |\n| Controlar computadores | Mind Key (lado do usuário) / Computer Token (lado do agente) |\n| Registrar uma conta de usuário | Nenhum (público) |\n| Fazer login | Nenhum (público) |\n| Criar / listar / excluir minds | JWT |\n| Compartilhar um mind com outro usuário | JWT |\n| Inscrever-se em notificações web push | JWT |\n| Ver log de auditoria | Mind Key |\n\n## A regra simples\n\n> [!TIP]\n> **Se toca os dados de um único mind → Mind Key.**\n> **Se gerencia a conta ou metadados de mind → JWT.**\n\n## Mind Key — token de acesso a dados\n\nUma Mind Key concede acesso aos **dados de um mind**. É um token de longa\nduração que nunca expira (até o mind ser excluído). Perfeita para:\n\n- Agentes LLM persistindo memórias entre sessões\n- Cron jobs em background\n- Configuração de servidor MCP\n- Integrações de webhook\n- Apps mobile lendo memória\n\n### O que a Mind Key pode fazer\n\n- `GET /memory/recall` — ler todas as memórias neste mind\n- `POST /memory` — armazenar/atualizar memórias\n- `GET /chat/poll` — ler mensagens de chat\n- `POST /chat/reply` — enviar mensagens de chat\n- `GET /mind/tasks` — listar tarefas\n- `POST /mind/task` — criar tarefas\n- `POST /script` — armazenar scripts\n- `POST /webhooks` — registrar webhooks\n- `POST /computers/:id/commands` — enfileirar comandos de computador\n\n### O que a Mind Key NÃO pode fazer\n\n- Criar / listar / excluir minds (precisa de JWT)\n- Compartilhar mind com outro usuário (precisa de JWT)\n- Ver informações da conta do usuário (precisa de JWT)\n- Inscrever-se em web push (precisa de JWT)\n\n## JWT — token de gerenciamento de conta\n\nUm JWT autentica a **conta do usuário**. Ele expira após 7 dias e é usado para\noperações em nível de conta que abrangem múltiplos minds ou envolvem outros\nusuários.\n\n### O que o JWT pode fazer\n\n- `POST /minds` — criar um novo mind (retorna uma nova Mind Key)\n- `GET /minds` — listar todos os minds deste usuário\n- `DELETE /minds/:id` — excluir um mind\n- `POST /sharing` — compartilhar um mind com outro usuário\n- `POST /push/subscribe` — inscrever em notificações web push\n- `GET /sharing` — listar compartilhamentos de mind\n\n### O que o JWT NÃO pode fazer\n\n- Ler / escrever memórias (precisa de Mind Key)\n- Enviar mensagens de chat (precisa de Mind Key)\n- Gerenciar tarefas (precisa de Mind Key)\n- Registrar webhooks (precisa de Mind Key)\n\n## Caso especial: Computer Token\n\nOs endpoints `/computers/me/*` (voltados ao agente, para o screen-remote-agent)\nusam um terceiro tipo de token: o **Computer Token**. Esse token é retornado por\n`POST /computers/register` ao resgatar um código de instalação, e é específico\npara um computador registrado.\n\n| Endpoint | Auth |\n|----------|------|\n| `GET /computers/me/poll` | Computer Token |\n| `POST /computers/me/commands/:cid/result` | Computer Token |\n| `GET /computers/list` | Mind Key ou JWT |\n| `POST /computers/:id/commands` | Mind Key ou JWT |\n\n## Padrões comuns\n\n### Padrão 1: agente LLM único\n\n1. Registre uma vez → obtenha JWT\n2. Crie um mind → obtenha Mind Key\n3. LLM usa a Mind Key para tudo\n\n### Padrão 2: agente multi-projeto\n\n1. Registre uma vez → obtenha JWT\n2. Crie múltiplos minds (work, personal, project-x) → obtenha múltiplas Mind Keys\n3. LLM carrega Mind Key diferente com base no contexto\n\n### Padrão 3: compartilhamento em equipe\n\n1. Usuário A cria um mind → obtém Mind Key A\n2. Usuário A compartilha com Usuário B via JWT (`POST /sharing`)\n3. Usuário B agora pode acessar via seu próprio JWT\n4. Para acesso LLM, Usuário B precisa criar sua própria Mind Key (ou usar a de A)\n\n### Padrão 4: servidor MCP\n\nServidores MCP sempre usam Mind Key (definida via variável de ambiente\n`SYNAPSE_MIND_KEY`). Uma instância de servidor MCP = um mind. Para acesso\nmulti-mind, rode múltiplas instâncias MCP ou implemente troca de mind no cliente.\n\n## Tabela de formato de tokens\n\n| Token | Formato | Exemplo |\n|-------|---------|---------|\n| Mind Key | `mk_` + 36 chars | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 chars | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Próximos passos\n\n- [Autenticação](/docs/getting-started/authentication) — guia completo de auth\n- [API de Usuário e Minds](/docs/api/user) — endpoints protegidos por JWT\n- [API de Memória](/docs/api/memory) — endpoints protegidos por Mind Key\n","content_html":"<h1>Mind Key vs JWT — qual usar quando?</h1>\n<p>O Synapse tem dois tokens de autenticação. Escolher o errado leva a erros 401.\nEste guia oferece uma estrutura clara de decisão.</p>\n<h2>Tabela de decisão rápida</h2>\n<table>\n<thead>\n<tr>\n<th>Você quer...</th>\n<th>Use</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Armazenar / recuperar memórias</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Enviar / fazer poll de mensagens de chat</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Gerenciar tarefas</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Armazenar scripts</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Registrar webhooks</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Controlar computadores</td>\n<td>Mind Key (lado do usuário) / Computer Token (lado do agente)</td>\n</tr>\n<tr>\n<td>Registrar uma conta de usuário</td>\n<td>Nenhum (público)</td>\n</tr>\n<tr>\n<td>Fazer login</td>\n<td>Nenhum (público)</td>\n</tr>\n<tr>\n<td>Criar / listar / excluir minds</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Compartilhar um mind com outro usuário</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Inscrever-se em notificações web push</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Ver log de auditoria</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>A regra simples</h2>\n<div class=\"callout callout-ok\">**Se toca os dados de um único mind → Mind Key.**\n**Se gerencia a conta ou metadados de mind → JWT.**</div><h2>Mind Key — token de acesso a dados</h2>\n<p>Uma Mind Key concede acesso aos <strong>dados de um mind</strong>. É um token de longa\nduração que nunca expira (até o mind ser excluído). Perfeita para:</p>\n<ul>\n<li>Agentes LLM persistindo memórias entre sessões</li>\n<li>Cron jobs em background</li>\n<li>Configuração de servidor MCP</li>\n<li>Integrações de webhook</li>\n<li>Apps mobile lendo memória</li>\n</ul>\n<h3>O que a Mind Key pode fazer</h3>\n<ul>\n<li><code>GET /memory/recall</code> — ler todas as memórias neste mind</li>\n<li><code>POST /memory</code> — armazenar/atualizar memórias</li>\n<li><code>GET /chat/poll</code> — ler mensagens de chat</li>\n<li><code>POST /chat/reply</code> — enviar mensagens de chat</li>\n<li><code>GET /mind/tasks</code> — listar tarefas</li>\n<li><code>POST /mind/task</code> — criar tarefas</li>\n<li><code>POST /script</code> — armazenar scripts</li>\n<li><code>POST /webhooks</code> — registrar webhooks</li>\n<li><code>POST /computers/:id/commands</code> — enfileirar comandos de computador</li>\n</ul>\n<h3>O que a Mind Key NÃO pode fazer</h3>\n<ul>\n<li>Criar / listar / excluir minds (precisa de JWT)</li>\n<li>Compartilhar mind com outro usuário (precisa de JWT)</li>\n<li>Ver informações da conta do usuário (precisa de JWT)</li>\n<li>Inscrever-se em web push (precisa de JWT)</li>\n</ul>\n<h2>JWT — token de gerenciamento de conta</h2>\n<p>Um JWT autentica a <strong>conta do usuário</strong>. Ele expira após 7 dias e é usado para\noperações em nível de conta que abrangem múltiplos minds ou envolvem outros\nusuários.</p>\n<h3>O que o JWT pode fazer</h3>\n<ul>\n<li><code>POST /minds</code> — criar um novo mind (retorna uma nova Mind Key)</li>\n<li><code>GET /minds</code> — listar todos os minds deste usuário</li>\n<li><code>DELETE /minds/:id</code> — excluir um mind</li>\n<li><code>POST /sharing</code> — compartilhar um mind com outro usuário</li>\n<li><code>POST /push/subscribe</code> — inscrever em notificações web push</li>\n<li><code>GET /sharing</code> — listar compartilhamentos de mind</li>\n</ul>\n<h3>O que o JWT NÃO pode fazer</h3>\n<ul>\n<li>Ler / escrever memórias (precisa de Mind Key)</li>\n<li>Enviar mensagens de chat (precisa de Mind Key)</li>\n<li>Gerenciar tarefas (precisa de Mind Key)</li>\n<li>Registrar webhooks (precisa de Mind Key)</li>\n</ul>\n<h2>Caso especial: Computer Token</h2>\n<p>Os endpoints <code>/computers/me/*</code> (voltados ao agente, para o screen-remote-agent)\nusam um terceiro tipo de token: o <strong>Computer Token</strong>. Esse token é retornado por\n<code>POST /computers/register</code> ao resgatar um código de instalação, e é específico\npara um computador registrado.</p>\n<table>\n<thead>\n<tr>\n<th>Endpoint</th>\n<th>Auth</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /computers/me/poll</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>POST /computers/me/commands/:cid/result</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>GET /computers/list</code></td>\n<td>Mind Key ou JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key ou JWT</td>\n</tr>\n</tbody></table>\n<h2>Padrões comuns</h2>\n<h3>Padrão 1: agente LLM único</h3>\n<ol>\n<li>Registre uma vez → obtenha JWT</li>\n<li>Crie um mind → obtenha Mind Key</li>\n<li>LLM usa a Mind Key para tudo</li>\n</ol>\n<h3>Padrão 2: agente multi-projeto</h3>\n<ol>\n<li>Registre uma vez → obtenha JWT</li>\n<li>Crie múltiplos minds (work, personal, project-x) → obtenha múltiplas Mind Keys</li>\n<li>LLM carrega Mind Key diferente com base no contexto</li>\n</ol>\n<h3>Padrão 3: compartilhamento em equipe</h3>\n<ol>\n<li>Usuário A cria um mind → obtém Mind Key A</li>\n<li>Usuário A compartilha com Usuário B via JWT (<code>POST /sharing</code>)</li>\n<li>Usuário B agora pode acessar via seu próprio JWT</li>\n<li>Para acesso LLM, Usuário B precisa criar sua própria Mind Key (ou usar a de A)</li>\n</ol>\n<h3>Padrão 4: servidor MCP</h3>\n<p>Servidores MCP sempre usam Mind Key (definida via variável de ambiente\n<code>SYNAPSE_MIND_KEY</code>). Uma instância de servidor MCP = um mind. Para acesso\nmulti-mind, rode múltiplas instâncias MCP ou implemente troca de mind no cliente.</p>\n<h2>Tabela de formato de tokens</h2>\n<table>\n<thead>\n<tr>\n<th>Token</th>\n<th>Formato</th>\n<th>Exemplo</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key</td>\n<td><code>mk_</code> + 36 chars</td>\n<td><code>mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789</code></td>\n</tr>\n<tr>\n<td>JWT</td>\n<td><code>eyJ</code> + base64</td>\n<td><code>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</code></td>\n</tr>\n<tr>\n<td>Computer Token</td>\n<td><code>ct_</code> + 36 chars</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Próximos passos</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Autenticação</a> — guia completo de auth</li>\n<li><a href=\"/docs/api/user\">API de Usuário e Minds</a> — endpoints protegidos por JWT</li>\n<li><a href=\"/docs/api/memory\">API de Memória</a> — endpoints protegidos por Mind Key</li>\n</ul>\n","urls":{"html":"/docs/getting-started/mind-key-vs-jwt","text":"/docs/getting-started/mind-key-vs-jwt?format=text","json":"/docs/getting-started/mind-key-vs-jwt?format=json","llm":"/docs/getting-started/mind-key-vs-jwt?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}