{"title":"Autenticación y Mind Keys","slug":"authentication","category":"getting-started","summary":"Cómo funciona la autenticación de Synapse: Mind Keys para agentes, JWTs para humanos, ?key= para herramientas que solo usan URL.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":544,"read_minutes":3,"llm_context":"Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).\nMind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)\nJWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)\nMind Key is shown only once at creation. Store it permanently.\nEach mind has exactly one Mind Key. Multiple minds = multiple keys.\n","lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Autenticación y Mind Keys\n\nSynapse usa dos métodos de autenticación, cada uno optimizado para un caso de\nuso diferente. Comprender la diferencia es esencial para construir integraciones\nfiables.\n\n## Dos métodos de autenticación\n\n| Método | Caso de uso | Límite de frecuencia | Expiración |\n|--------|----------|------------|--------|\n| **Mind Key** | Agentes LLM, herramientas automatizadas | Ninguno (cabecera) / 60 min (query) | Nunca |\n| **JWT** | Interfaz humana, operaciones de cuenta | Ninguno | 7 días |\n\n## Mind Key (para agentes)\n\nUn Mind Key es un token de API con ámbito de tenant. Autentica los datos de un\nsolo mind (memorias, tareas, chat, scripts, etc.). Úselo para:\n\n- Agentes LLM que llaman a la API\n- Scripts de automatización en segundo plano\n- Configuración del servidor MCP\n- Cualquier integración de larga duración\n\n### Autenticación por cabecera (recomendada)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Parámetro de consulta (para herramientas que solo usan URL)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> El parámetro de consulta `?key=` está limitado a **60 peticiones por minuto**.\n> La cabecera Bearer no tiene límite de frecuencia. Use la cabecera siempre que\n> su cliente admita cabeceras personalizadas.\n\n### Crear un Mind Key\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/minds \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Work Mind\", \"description\": \"Project memories\"}'\n```\n\nLa respuesta incluye `mind_key` — **guárdelo de inmediato**, solo se muestra una\nvez.\n\n### Listar sus minds\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Eliminar un mind (¡irreversible!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (para humanos)\n\nLos JWT autentican la **cuenta de usuario**, no un mind específico. Úselos para:\n\n- Registro y login de cuenta\n- Crear / listar / eliminar minds\n- Compartir minds con otros usuarios\n- Gestión de suscripciones Web Push\n\n### Registro\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nDevuelve: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Login\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nDevuelve: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Expiración del JWT\n\nLos JWT expiran después de **7 días**. Cuando un JWT expira, simplemente llame\na `/login` de nuevo para obtener uno nuevo. El Mind Key nunca expira, de modo\nque las integraciones de agente existentes siguen funcionando.\n\n## Mejores prácticas de seguridad\n\n> [!CRITICAL]\n> - **Nunca confíe Mind Keys a git.** Use variables de entorno.\n> - **Nunca registre Mind Keys en logs.** Enmascárelos (`mk_***...***xyz`).\n> - **Rote las claves** si sospecha de una fuga (elimine el mind, cree uno nuevo).\n> - **Use un mind por proyecto** para limitar el radio de impacto si se filtra una clave.\n\n### Patrón con variables de entorno\n\n```bash\n# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone\n```\n\n```typescript\n// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n headers: { Authorization: `Bearer ${mindKey}` },\n});\n```\n\n### Configuración del servidor MCP\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_yourMindKeyHere\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n## Patrón multi-mind\n\nCada usuario puede tener múltiples minds. Patrones comunes:\n\n| Nombre del mind | Propósito |\n|-----------|---------|\n| `work` | Memorias de trabajo |\n| `personal` | Preferencias personales, familia |\n| `project-synapse` | Contexto de un proyecto específico |\n| `learning-german` | Progreso de aprendizaje |\n| `assistant-default` | Fallback de propósito general |\n\nUse diferentes Mind Keys para diferentes sesiones LLM a fin de mantener los\ncontextos aislados.\n\n## Límites de frecuencia\n\n| Método de auth | Límite | Ámbito |\n|-------------|-------|-------|\n| Mind Key (cabecera) | Ninguno | Por mind |\n| Mind Key (?key=) | 60/min | Por IP |\n| JWT (cabecera) | Ninguno | Por usuario |\n| Endpoints públicos | Ninguno | Global |\n\nLas cabeceras de límite de frecuencia (`X-RateLimit-Limit`,\n`X-RateLimit-Remaining`, `Retry-After`) se incluyen en las respuestas cuando\naplica.\n\n## Próximos pasos\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — cuándo usar cada uno\n- [API de Memory](/docs/api/memory) — qué puede hacer con un Mind Key\n- [API de User](/docs/api/user) — gestión de cuenta con JWTs\n","content_html":"

Autenticación y Mind Keys

\n

Synapse usa dos métodos de autenticación, cada uno optimizado para un caso de\nuso diferente. Comprender la diferencia es esencial para construir integraciones\nfiables.

\n

Dos métodos de autenticación

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MétodoCaso de usoLímite de frecuenciaExpiración
Mind KeyAgentes LLM, herramientas automatizadasNinguno (cabecera) / 60 min (query)Nunca
JWTInterfaz humana, operaciones de cuentaNinguno7 días
\n

Mind Key (para agentes)

\n

Un Mind Key es un token de API con ámbito de tenant. Autentica los datos de un\nsolo mind (memorias, tareas, chat, scripts, etc.). Úselo para:

\n\n

Autenticación por cabecera (recomendada)

\n
curl -H "Authorization: Bearer mk_yourMindKeyHere" \\\n     https://synapse.schaefer.zone/memory/recall

Parámetro de consulta (para herramientas que solo usan URL)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
El parámetro de consulta `?key=` está limitado a **60 peticiones por minuto**.\nLa cabecera Bearer no tiene límite de frecuencia. Use la cabecera siempre que\nsu cliente admita cabeceras personalizadas.

Crear un Mind Key

\n
curl -X POST https://synapse.schaefer.zone/minds \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"name": "Work Mind", "description": "Project memories"}'

La respuesta incluye mind_key — guárdelo de inmediato, solo se muestra una\nvez.

\n

Listar sus minds

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds

Eliminar un mind (¡irreversible!)

\n
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds/m_xyz789

JWT (para humanos)

\n

Los JWT autentican la cuenta de usuario, no un mind específico. Úselos para:

\n\n

Registro

\n
curl -X POST https://synapse.schaefer.zone/register \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Devuelve: { "jwt": "eyJ...", "user": {...} }

\n

Login

\n
curl -X POST https://synapse.schaefer.zone/login \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Devuelve: { "jwt": "eyJ...", "user": {...} }

\n

Expiración del JWT

\n

Los JWT expiran después de 7 días. Cuando un JWT expira, simplemente llame\na /login de nuevo para obtener uno nuevo. El Mind Key nunca expira, de modo\nque las integraciones de agente existentes siguen funcionando.

\n

Mejores prácticas de seguridad

\n

Patrón con variables de entorno

\n
# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone
// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n  headers: { Authorization: `Bearer ${mindKey}` },\n});

Configuración del servidor MCP

\n
{\n  "mcpServers": {\n    "synapse": {\n      "command": "npx",\n      "args": ["-y", "synapse-mcp-api@latest"],\n      "env": {\n        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",\n        "SYNAPSE_URL": "https://synapse.schaefer.zone"\n      }\n    }\n  }\n}

Patrón multi-mind

\n

Cada usuario puede tener múltiples minds. Patrones comunes:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Nombre del mindPropósito
workMemorias de trabajo
personalPreferencias personales, familia
project-synapseContexto de un proyecto específico
learning-germanProgreso de aprendizaje
assistant-defaultFallback de propósito general
\n

Use diferentes Mind Keys para diferentes sesiones LLM a fin de mantener los\ncontextos aislados.

\n

Límites de frecuencia

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Método de authLímiteÁmbito
Mind Key (cabecera)NingunoPor mind
Mind Key (?key=)60/minPor IP
JWT (cabecera)NingunoPor usuario
Endpoints públicosNingunoGlobal
\n

Las cabeceras de límite de frecuencia (X-RateLimit-Limit,\nX-RateLimit-Remaining, Retry-After) se incluyen en las respuestas cuando\naplica.

\n

Próximos pasos

\n\n","urls":{"html":"/docs/getting-started/authentication","text":"/docs/getting-started/authentication?format=text","json":"/docs/getting-started/authentication?format=json","llm":"/docs/getting-started/authentication?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}