# 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

| Método | Caso de uso | Límite de frecuencia | Expiración |
|--------|----------|------------|--------|
| **Mind Key** | Agentes LLM, herramientas automatizadas | Ninguno (cabecera) / 60 min (query) | Nunca |
| **JWT** | Interfaz humana, operaciones de cuenta | Ninguno | 7 días |

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

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

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

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

> [!WARNING]
> El parámetro de consulta `?key=` está limitado a **60 peticiones por minuto**.
> La cabecera Bearer no tiene límite de frecuencia. Use la cabecera siempre que
> su cliente admita cabeceras personalizadas.

### Crear un Mind Key

```bash
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

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

### Eliminar un mind (¡irreversible!)

```bash
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

```bash
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

```bash
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

> [!CRITICAL]
> - **Nunca confíe Mind Keys a git.** Use variables de entorno.
> - **Nunca registre Mind Keys en logs.** Enmascárelos (`mk_***...***xyz`).
> - **Rote las claves** si sospecha de una fuga (elimine el mind, cree uno nuevo).
> - **Use un mind por proyecto** para limitar el radio de impacto si se filtra una clave.

### Patrón con variables de entorno

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

```typescript
// 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

```json
{
  "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:

| Nombre del mind | Propósito |
|-----------|---------|
| `work` | Memorias de trabajo |
| `personal` | Preferencias personales, familia |
| `project-synapse` | Contexto de un proyecto específico |
| `learning-german` | Progreso de aprendizaje |
| `assistant-default` | Fallback de propósito general |

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

## Límites de frecuencia

| Método de auth | Límite | Ámbito |
|-------------|-------|-------|
| Mind Key (cabecera) | Ninguno | Por mind |
| Mind Key (?key=) | 60/min | Por IP |
| JWT (cabecera) | Ninguno | Por usuario |
| Endpoints públicos | Ninguno | Global |

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](/docs/getting-started/mind-key-vs-jwt) — cuándo usar cada uno
- [API de Memory](/docs/api/memory) — qué puede hacer con un Mind Key
- [API de User](/docs/api/user) — gestión de cuenta con JWTs