# Mind Key vs JWT — quando usare quale?

Synapse ha due token di autenticazione. Scegliere quello sbagliato porta a
errori 401. Questa guida le dà un framework decisionale chiaro.

## Tabella decisionale rapida

| Vuole... | Usi |
|----------------|-----|
| Memorizzare / richiamare memorie | Mind Key |
| Inviare / polling messaggi chat | Mind Key |
| Gestire attività | Mind Key |
| Memorizzare script | Mind Key |
| Registrare webhook | Mind Key |
| Controllare computer | Mind Key (lato utente) / Computer Token (lato agente) |
| Registrare un account utente | Nessuna (pubblico) |
| Login | Nessuna (pubblico) |
| Creare / elencare / eliminare menti | JWT |
| Condividere una mente con un altro utente | JWT |
| Sottoscrivere notifiche web push | JWT |
| Vedere il log di audit | Mind Key |

## La regola semplice

> [!TIP]
> **Se tocca i dati di una singola mente → Mind Key.**
> **Se gestisce l'account o i metadati delle menti → JWT.**

## Mind Key — token di accesso ai dati

Una Mind Key concede accesso ai **dati di una mente**. È un token long-lived
che non scade mai (fino a quando la mente viene eliminata). Perfetta per:

- Agenti LLM che persistono memorie tra sessioni
- Cron job in background
- Configurazione del server MCP
- Integrazioni webhook
- App mobile che leggono la memoria

### Cosa può fare la Mind Key

- `GET /memory/recall` — leggere tutte le memorie in questa mente
- `POST /memory` — memorizzare/aggiornare memorie
- `GET /chat/poll` — leggere i messaggi chat
- `POST /chat/reply` — inviare messaggi chat
- `GET /mind/tasks` — elencare le attività
- `POST /mind/task` — creare attività
- `POST /script` — memorizzare script
- `POST /webhooks` — registrare webhook
- `POST /computers/:id/commands` — accodare comandi per computer

### Cosa NON può fare la Mind Key

- Creare / elencare / eliminare menti (serve JWT)
- Condividere una mente con un altro utente (serve JWT)
- Vedere le informazioni dell'account utente (serve JWT)
- Sottoscrivere web push (serve JWT)

## JWT — token di gestione account

Un JWT autentica l'**account utente**. Scade dopo 7 giorni ed è usato per
operazioni a livello di account che coprono più menti o coinvolgono altri
utenti.

### Cosa può fare il JWT

- `POST /minds` — creare una nuova mente (restituisce una nuova Mind Key)
- `GET /minds` — elencare tutte le menti di questo utente
- `DELETE /minds/:id` — eliminare una mente
- `POST /sharing` — condividere una mente con un altro utente
- `POST /push/subscribe` — sottoscrivere notifiche web push
- `GET /sharing` — elencare le condivisioni delle menti

### Cosa NON può fare il JWT

- Leggere / scrivere memorie (serve Mind Key)
- Inviare messaggi chat (serve Mind Key)
- Gestire attività (serve Mind Key)
- Registrare webhook (serve Mind Key)

## Caso speciale: Computer Token

Gli endpoint `/computers/me/*` (lato agente, per lo screen-remote-agent) usano
un terzo tipo di token: il **Computer Token**. Questo token viene restituito da
`POST /computers/register` quando si riscatta un codice di installazione, ed è
specifico per un computer registrato.

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

## Modelli comuni

### Modello 1: agente LLM singolo

1. Si registra una volta → ottiene JWT
2. Crea una mente → ottiene Mind Key
3. L'LLM usa la Mind Key per tutto

### Modello 2: agente multi-progetto

1. Si registra una volta → ottiene JWT
2. Crea menti multiple (work, personal, project-x) → ottiene Mind Key multiple
3. L'LLM carica Mind Key diverse in base al contesto

### Modello 3: condivisione di team

1. L'Utente A crea una mente → ottiene Mind Key A
2. L'Utente A condivide con l'Utente B tramite JWT (`POST /sharing`)
3. L'Utente B ora può accedere tramite il suo stesso JWT
4. Per l'accesso LLM, l'Utente B deve creare la sua Mind Key (o usare quella di A)

### Modello 4: server MCP

I server MCP usano sempre la Mind Key (impostata tramite variabile env
`SYNAPSE_MIND_KEY`). Un'istanza del server MCP = una mente. Per accesso
multi-mente, esegua più istanze MCP o implementi cambio mente lato client.

## Sintesi dei formati dei token

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

## Prossimi passi

- [Autenticazione](/docs/getting-started/authentication) — guida auth completa
- [User & Minds API](/docs/api/user) — endpoint protetti da JWT
- [Memory API](/docs/api/memory) — endpoint protetti da Mind Key