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

La regola semplice

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.

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

Prossimi passi

• Autenticazione — guida auth completa
• User & Minds API — endpoint protetti da JWT
• Memory API — endpoint protetti da Mind Key