{"title":"Mind Key vs JWT — ¿Cuándo usar cada uno?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Guía de decisión: Mind Key para acceso a datos del agente, JWT para gestión de cuenta.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":770,"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":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Mind Key vs JWT — ¿Cuándo usar cada uno?\n\nSynapse tiene dos tokens de autenticación. Elegir el incorrecto lleva a errores\n401. Esta guía le ofrece un marco de decisión claro.\n\n## Tabla de decisión rápida\n\n| Quiere... | Usar |\n|----------------|-----|\n| Almacenar / recuperar memorias | Mind Key |\n| Enviar / hacer poll de mensajes de chat | Mind Key |\n| Gestionar tareas | Mind Key |\n| Almacenar scripts | Mind Key |\n| Registrar webhooks | Mind Key |\n| Controlar computadoras | Mind Key (lado usuario) / Computer Token (lado agente) |\n| Registrar una cuenta de usuario | Ninguno (público) |\n| Iniciar sesión | Ninguno (público) |\n| Crear / listar / eliminar minds | JWT |\n| Compartir un mind con otro usuario | JWT |\n| Suscribirse a notificaciones web push | JWT |\n| Ver el log de auditoría | Mind Key |\n\n## La regla simple\n\n> [!TIP]\n> **Si toca los datos de un solo mind → Mind Key.**\n> **Si gestiona la cuenta o los metadatos del mind → JWT.**\n\n## Mind Key — token de acceso a datos\n\nUn Mind Key otorga acceso a **los datos de un mind**. Es un token de larga\nduración que nunca expira (hasta que se elimina el mind). Perfecto para:\n\n- Agentes LLM que persisten memorias entre sesiones\n- Trabajos cron en segundo plano\n- Configuración del servidor MCP\n- Integraciones de webhooks\n- Apps móviles que leen memoria\n\n### Qué puede hacer el Mind Key\n\n- `GET /memory/recall` — leer todas las memorias de este mind\n- `POST /memory` — almacenar/actualizar memorias\n- `GET /chat/poll` — leer mensajes de chat\n- `POST /chat/reply` — enviar mensajes de chat\n- `GET /mind/tasks` — listar tareas\n- `POST /mind/task` — crear tareas\n- `POST /script` — almacenar scripts\n- `POST /webhooks` — registrar webhooks\n- `POST /computers/:id/commands` — encolar comandos de computadora\n\n### Qué NO puede hacer el Mind Key\n\n- Crear / listar / eliminar minds (necesita JWT)\n- Compartir un mind con otro usuario (necesita JWT)\n- Ver la información de la cuenta de usuario (necesita JWT)\n- Suscribirse a web push (necesita JWT)\n\n## JWT — token de gestión de cuenta\n\nUn JWT autentica la **cuenta de usuario**. Expira después de 7 días y se usa\npara operaciones a nivel de cuenta que abarcan múltiples minds o involucran a\notros usuarios.\n\n### Qué puede hacer el JWT\n\n- `POST /minds` — crear un nuevo mind (devuelve un nuevo Mind Key)\n- `GET /minds` — listar todos los minds de este usuario\n- `DELETE /minds/:id` — eliminar un mind\n- `POST /sharing` — compartir un mind con otro usuario\n- `POST /push/subscribe` — suscribirse a notificaciones web push\n- `GET /sharing` — listar comparticiones de mind\n\n### Qué NO puede hacer el JWT\n\n- Leer / escribir memorias (necesita Mind Key)\n- Enviar mensajes de chat (necesita Mind Key)\n- Gestionar tareas (necesita Mind Key)\n- Registrar webhooks (necesita Mind Key)\n\n## Caso especial: Computer Token\n\nLos endpoints `/computers/me/*` (del lado del agente, para el\nscreen-remote-agent) usan un tercer tipo de token: el **Computer Token**. Este\ntoken lo devuelve `POST /computers/register` al canjear un código de\ninstalación, y es específico a una computadora registrada.\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 o JWT |\n| `POST /computers/:id/commands` | Mind Key o JWT |\n\n## Patrones comunes\n\n### Patrón 1: Agente LLM único\n\n1. Registrar una vez → obtener JWT\n2. Crear un mind → obtener Mind Key\n3. El LLM usa el Mind Key para todo\n\n### Patrón 2: Agente multi-proyecto\n\n1. Registrar una vez → obtener JWT\n2. Crear múltiples minds (trabajo, personal, proyecto-x) → obtener múltiples Mind Keys\n3. El LLM carga diferente Mind Key según el contexto\n\n### Patrón 3: Compartir en equipo\n\n1. El usuario A crea un mind → obtiene el Mind Key A\n2. El usuario A comparte con el usuario B vía JWT (`POST /sharing`)\n3. El usuario B ya puede acceder vía su propio JWT\n4. Para acceso LLM, el usuario B necesita crear su propio Mind Key (o usar el de A)\n\n### Patrón 4: Servidor MCP\n\nLos servidores MCP siempre usan Mind Key (establecido vía la variable de entorno\n`SYNAPSE_MIND_KEY`). Una instancia del servidor MCP = un mind. Para acceso\nmulti-mind, ejecute múltiples instancias MCP o implemente cambio de mind del\nlado del cliente.\n\n## Hoja de referencia de formato de tokens\n\n| Token | Formato | Ejemplo |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36 caracteres | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 caracteres | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Próximos pasos\n\n- [Autenticación](/docs/getting-started/authentication) — guía completa de auth\n- [API de User y Minds](/docs/api/user) — endpoints protegidos con JWT\n- [API de Memory](/docs/api/memory) — endpoints protegidos con Mind Key\n","content_html":"<h1>Mind Key vs JWT — ¿Cuándo usar cada uno?</h1>\n<p>Synapse tiene dos tokens de autenticación. Elegir el incorrecto lleva a errores\n401. Esta guía le ofrece un marco de decisión claro.</p>\n<h2>Tabla de decisión rápida</h2>\n<table>\n<thead>\n<tr>\n<th>Quiere...</th>\n<th>Usar</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Almacenar / recuperar memorias</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Enviar / hacer poll de mensajes de chat</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Gestionar tareas</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Almacenar 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 computadoras</td>\n<td>Mind Key (lado usuario) / Computer Token (lado agente)</td>\n</tr>\n<tr>\n<td>Registrar una cuenta de usuario</td>\n<td>Ninguno (público)</td>\n</tr>\n<tr>\n<td>Iniciar sesión</td>\n<td>Ninguno (público)</td>\n</tr>\n<tr>\n<td>Crear / listar / eliminar minds</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Compartir un mind con otro usuario</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Suscribirse a notificaciones web push</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Ver el log de auditoría</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>La regla simple</h2>\n<div class=\"callout callout-ok\">**Si toca los datos de un solo mind → Mind Key.**\n**Si gestiona la cuenta o los metadatos del mind → JWT.**</div><h2>Mind Key — token de acceso a datos</h2>\n<p>Un Mind Key otorga acceso a <strong>los datos de un mind</strong>. Es un token de larga\nduración que nunca expira (hasta que se elimina el mind). Perfecto para:</p>\n<ul>\n<li>Agentes LLM que persisten memorias entre sesiones</li>\n<li>Trabajos cron en segundo plano</li>\n<li>Configuración del servidor MCP</li>\n<li>Integraciones de webhooks</li>\n<li>Apps móviles que leen memoria</li>\n</ul>\n<h3>Qué puede hacer el Mind Key</h3>\n<ul>\n<li><code>GET /memory/recall</code> — leer todas las memorias de este mind</li>\n<li><code>POST /memory</code> — almacenar/actualizar memorias</li>\n<li><code>GET /chat/poll</code> — leer mensajes de chat</li>\n<li><code>POST /chat/reply</code> — enviar mensajes de chat</li>\n<li><code>GET /mind/tasks</code> — listar tareas</li>\n<li><code>POST /mind/task</code> — crear tareas</li>\n<li><code>POST /script</code> — almacenar scripts</li>\n<li><code>POST /webhooks</code> — registrar webhooks</li>\n<li><code>POST /computers/:id/commands</code> — encolar comandos de computadora</li>\n</ul>\n<h3>Qué NO puede hacer el Mind Key</h3>\n<ul>\n<li>Crear / listar / eliminar minds (necesita JWT)</li>\n<li>Compartir un mind con otro usuario (necesita JWT)</li>\n<li>Ver la información de la cuenta de usuario (necesita JWT)</li>\n<li>Suscribirse a web push (necesita JWT)</li>\n</ul>\n<h2>JWT — token de gestión de cuenta</h2>\n<p>Un JWT autentica la <strong>cuenta de usuario</strong>. Expira después de 7 días y se usa\npara operaciones a nivel de cuenta que abarcan múltiples minds o involucran a\notros usuarios.</p>\n<h3>Qué puede hacer el JWT</h3>\n<ul>\n<li><code>POST /minds</code> — crear un nuevo mind (devuelve un nuevo Mind Key)</li>\n<li><code>GET /minds</code> — listar todos los minds de este usuario</li>\n<li><code>DELETE /minds/:id</code> — eliminar un mind</li>\n<li><code>POST /sharing</code> — compartir un mind con otro usuario</li>\n<li><code>POST /push/subscribe</code> — suscribirse a notificaciones web push</li>\n<li><code>GET /sharing</code> — listar comparticiones de mind</li>\n</ul>\n<h3>Qué NO puede hacer el JWT</h3>\n<ul>\n<li>Leer / escribir memorias (necesita Mind Key)</li>\n<li>Enviar mensajes de chat (necesita Mind Key)</li>\n<li>Gestionar tareas (necesita Mind Key)</li>\n<li>Registrar webhooks (necesita Mind Key)</li>\n</ul>\n<h2>Caso especial: Computer Token</h2>\n<p>Los endpoints <code>/computers/me/*</code> (del lado del agente, para el\nscreen-remote-agent) usan un tercer tipo de token: el <strong>Computer Token</strong>. Este\ntoken lo devuelve <code>POST /computers/register</code> al canjear un código de\ninstalación, y es específico a una computadora registrada.</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 o JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key o JWT</td>\n</tr>\n</tbody></table>\n<h2>Patrones comunes</h2>\n<h3>Patrón 1: Agente LLM único</h3>\n<ol>\n<li>Registrar una vez → obtener JWT</li>\n<li>Crear un mind → obtener Mind Key</li>\n<li>El LLM usa el Mind Key para todo</li>\n</ol>\n<h3>Patrón 2: Agente multi-proyecto</h3>\n<ol>\n<li>Registrar una vez → obtener JWT</li>\n<li>Crear múltiples minds (trabajo, personal, proyecto-x) → obtener múltiples Mind Keys</li>\n<li>El LLM carga diferente Mind Key según el contexto</li>\n</ol>\n<h3>Patrón 3: Compartir en equipo</h3>\n<ol>\n<li>El usuario A crea un mind → obtiene el Mind Key A</li>\n<li>El usuario A comparte con el usuario B vía JWT (<code>POST /sharing</code>)</li>\n<li>El usuario B ya puede acceder vía su propio JWT</li>\n<li>Para acceso LLM, el usuario B necesita crear su propio Mind Key (o usar el de A)</li>\n</ol>\n<h3>Patrón 4: Servidor MCP</h3>\n<p>Los servidores MCP siempre usan Mind Key (establecido vía la variable de entorno\n<code>SYNAPSE_MIND_KEY</code>). Una instancia del servidor MCP = un mind. Para acceso\nmulti-mind, ejecute múltiples instancias MCP o implemente cambio de mind del\nlado del cliente.</p>\n<h2>Hoja de referencia de formato de tokens</h2>\n<table>\n<thead>\n<tr>\n<th>Token</th>\n<th>Formato</th>\n<th>Ejemplo</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key</td>\n<td><code>mk_</code> + 36 caracteres</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 caracteres</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Próximos pasos</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Autenticación</a> — guía completa de auth</li>\n<li><a href=\"/docs/api/user\">API de User y Minds</a> — endpoints protegidos con JWT</li>\n<li><a href=\"/docs/api/memory\">API de Memory</a> — endpoints protegidos con 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"]}