# 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

| Quiere... | Usar |
|----------------|-----|
| Almacenar / recuperar memorias | Mind Key |
| Enviar / hacer poll de mensajes de chat | Mind Key |
| Gestionar tareas | Mind Key |
| Almacenar scripts | Mind Key |
| Registrar webhooks | Mind Key |
| Controlar computadoras | Mind Key (lado usuario) / Computer Token (lado agente) |
| Registrar una cuenta de usuario | Ninguno (público) |
| Iniciar sesión | Ninguno (público) |
| Crear / listar / eliminar minds | JWT |
| Compartir un mind con otro usuario | JWT |
| Suscribirse a notificaciones web push | JWT |
| Ver el log de auditoría | Mind Key |

## La regla simple

> [!TIP]
> **Si toca los datos de un solo mind → Mind Key.**
> **Si gestiona la cuenta o los metadatos del mind → JWT.**

## 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.

| Endpoint | Auth |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key o JWT |
| `POST /computers/:id/commands` | Mind Key o JWT |

## 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

| Token | Formato | Ejemplo |
|-------|--------|---------|
| Mind Key | `mk_` + 36 caracteres | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 caracteres | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Próximos pasos

- [Autenticación](/docs/getting-started/authentication) — guía completa de auth
- [API de User y Minds](/docs/api/user) — endpoints protegidos con JWT
- [API de Memory](/docs/api/memory) — endpoints protegidos con Mind Key