# Autenticazione e Mind Key

Synapse usa due metodi di autenticazione, ciascuno ottimizzato per un caso
d'uso diverso. Comprendere la differenza è essenziale per costruire
integrazioni affidabili.

## Due metodi di auth

| Metodo | Caso d'uso | Rate limit | Scadenza |
|--------|----------|------------|--------|
| **Mind Key** | Agenti LLM, strumenti automatizzati | Nessuno (header) / 60 min (query) | Mai |
| **JWT** | UI human-facing, operazioni account | Nessuno | 7 giorni |

## Mind Key (per agenti)

Una Mind Key è un token API con scope tenant. Autentica i dati di una singola
mente (memorie, attività, chat, script, ecc.). La usi per:

- Agenti LLM che chiamano l'API
- Script di automazione in background
- Configurazione del server MCP
- Qualsiasi integrazione long-lived

### Autenticazione tramite header (consigliata)

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

### Parametro query (per strumenti solo-URL)

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

> [!WARNING]
> Il parametro query `?key=` è limitato a **60 richieste al minuto**.
> L'header Bearer non ha rate limit. Usi l'header quando il suo client
> supporta header personalizzati.

### Creare una 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 risposta include `mind_key` — **la salvi immediatamente**, viene mostrata
una sola volta.

### Elencare le sue menti

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

### Eliminare una mente (irreversibile!)

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

## JWT (per umani)

I JWT autenticano l'**account utente**, non una specifica mente. Li usi per:

- Registrazione e login dell'account
- Creare / elencare / eliminare menti
- Condividere menti con altri utenti
- Gestione delle sottoscrizioni Web Push

### Registrazione

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

Restituisce: `{ "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"}'
```

Restituisce: `{ "jwt": "eyJ...", "user": {...} }`

### Scadenza del JWT

I JWT scadono dopo **7 giorni**. Quando un JWT scade, chiami semplicemente
`/login` nuovamente per ottenerne uno nuovo. La Mind Key non scade mai, quindi
le integrazioni agente esistenti continuano a funzionare.

## Best practice di sicurezza

> [!CRITICAL]
> - **Non committi mai le Mind Key su git.** Usi variabili di ambiente.
> - **Non logghi mai le Mind Key.** Le mascheri nei log (`mk_***...***xyz`).
> - **Roti le chiavi** se sospetta una leak (elimini la mente, ne crei una nuova).
> - **Usi una mente per progetto** per limitare il raggio d'azione se una chiave leaka.

### Modello con variabili di ambiente

```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}` },
});
```

### Configurazione del server MCP

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

## Modello multi-mente

Ogni utente può avere menti multiple. Modelli comuni:

| Nome mente | Scopo |
|-----------|---------|
| `work` | Memorie relative al lavoro |
| `personal` | Preferenze personali, famiglia |
| `project-synapse` | Contesto di progetto specifico |
| `learning-german` | Avanzamento dell'apprendimento |
| `assistant-default` | Fallback generico |

Usi Mind Key diverse per sessioni LLM diverse per mantenere i contesti
isolati.

## Limiti di traffico

| Metodo di auth | Limite | Ambito |
|-------------|-------|-------|
| Mind Key (header) | Nessuno | Per-mente |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | Nessuno | Per-utente |
| Endpoint pubblici | Nessuno | Globale |

Gli header di rate limit (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,
`Retry-After`) sono inclusi nelle risposte quando applicabile.

## Prossimi passi

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — quando usare quale
- [Memory API](/docs/api/memory) — cosa può fare con una Mind Key
- [API User](/docs/api/user) — gestione account con JWT