Autenticación y Mind Keys

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

Dos métodos de autenticación

Mind Key (para agentes)

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

• Agentes LLM que llaman a la API
• Scripts de automatización en segundo plano
• Configuración del servidor MCP
• Cualquier integración de larga duración

Autenticación por cabecera (recomendada)

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

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

curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere

Crear un Mind Key

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

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

Listar sus minds

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

Eliminar un mind (¡irreversible!)

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

JWT (para humanos)

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

• Registro y login de cuenta
• Crear / listar / eliminar minds
• Compartir minds con otros usuarios
• Gestión de suscripciones Web Push

Registro

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

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

Login

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

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

Expiración del JWT

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

Mejores prácticas de seguridad

Patrón con variables de entorno

# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone

// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});

Configuración del servidor MCP

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

Patrón multi-mind

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

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

Límites de frecuencia

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

Próximos pasos

• Mind Key vs JWT — cuándo usar cada uno
• API de Memory — qué puede hacer con un Mind Key
• API de User — gestión de cuenta con JWTs