Mind Key vs JWT — ¿Cuándo usar cada uno?

Synapse tiene dos tokens de autenticación. Elegir el incorrecto lleva a errores 401. Esta guía le ofrece un marco de decisión claro.

Tabla de decisión rápida

La regla simple

Mind Key — token de acceso a datos

Un Mind Key otorga acceso a los datos de un mind. Es un token de larga duración que nunca expira (hasta que se elimina el mind). Perfecto para:

• Agentes LLM que persisten memorias entre sesiones
• Trabajos cron en segundo plano
• Configuración del servidor MCP
• Integraciones de webhooks
• Apps móviles que leen memoria

Qué puede hacer el Mind Key

• GET /memory/recall — leer todas las memorias de este mind
• POST /memory — almacenar/actualizar memorias
• GET /chat/poll — leer mensajes de chat
• POST /chat/reply — enviar mensajes de chat
• GET /mind/tasks — listar tareas
• POST /mind/task — crear tareas
• POST /script — almacenar scripts
• POST /webhooks — registrar webhooks
• POST /computers/:id/commands — encolar comandos de computadora

Qué NO puede hacer el Mind Key

• Crear / listar / eliminar minds (necesita JWT)
• Compartir un mind con otro usuario (necesita JWT)
• Ver la información de la cuenta de usuario (necesita JWT)
• Suscribirse a web push (necesita JWT)

JWT — token de gestión de cuenta

Un JWT autentica la cuenta de usuario. Expira después de 7 días y se usa para operaciones a nivel de cuenta que abarcan múltiples minds o involucran a otros usuarios.

Qué puede hacer el JWT

• POST /minds — crear un nuevo mind (devuelve un nuevo Mind Key)
• GET /minds — listar todos los minds de este usuario
• DELETE /minds/:id — eliminar un mind
• POST /sharing — compartir un mind con otro usuario
• POST /push/subscribe — suscribirse a notificaciones web push
• GET /sharing — listar comparticiones de mind

Qué NO puede hacer el JWT

• Leer / escribir memorias (necesita Mind Key)
• Enviar mensajes de chat (necesita Mind Key)
• Gestionar tareas (necesita Mind Key)
• Registrar webhooks (necesita Mind Key)

Caso especial: Computer Token

Los endpoints /computers/me/* (del lado del agente, para el screen-remote-agent) usan un tercer tipo de token: el Computer Token. Este token lo devuelve POST /computers/register al canjear un código de instalación, y es específico a una computadora registrada.

Patrones comunes

Patrón 1: Agente LLM único

1. Registrar una vez → obtener JWT
2. Crear un mind → obtener Mind Key
3. El LLM usa el Mind Key para todo

Patrón 2: Agente multi-proyecto

1. Registrar una vez → obtener JWT
2. Crear múltiples minds (trabajo, personal, proyecto-x) → obtener múltiples Mind Keys
3. El LLM carga diferente Mind Key según el contexto

Patrón 3: Compartir en equipo

1. El usuario A crea un mind → obtiene el Mind Key A
2. El usuario A comparte con el usuario B vía JWT (POST /sharing)
3. El usuario B ya puede acceder vía su propio JWT
4. Para acceso LLM, el usuario B necesita crear su propio Mind Key (o usar el de A)

Patrón 4: Servidor MCP

Los servidores MCP siempre usan Mind Key (establecido vía la variable de entorno SYNAPSE_MIND_KEY). Una instancia del servidor MCP = un mind. Para acceso multi-mind, ejecute múltiples instancias MCP o implemente cambio de mind del lado del cliente.

Hoja de referencia de formato de tokens

Próximos pasos

• Autenticación — guía completa de auth
• API de User y Minds — endpoints protegidos con JWT
• API de Memory — endpoints protegidos con Mind Key