{"title":"Mind Key vs JWT — quando usare quale?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Guida decisionale: Mind Key per accesso dati agente, JWT per gestione account.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":737,"read_minutes":4,"llm_context":"Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.\nJWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.\nSimple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.\nException: /computers/me/* uses Computer Token (not Mind Key or JWT).\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Mind Key vs JWT — quando usare quale?\n\nSynapse ha due token di autenticazione. Scegliere quello sbagliato porta a\nerrori 401. Questa guida le dà un framework decisionale chiaro.\n\n## Tabella decisionale rapida\n\n| Vuole... | Usi |\n|----------------|-----|\n| Memorizzare / richiamare memorie | Mind Key |\n| Inviare / polling messaggi chat | Mind Key |\n| Gestire attività | Mind Key |\n| Memorizzare script | Mind Key |\n| Registrare webhook | Mind Key |\n| Controllare computer | Mind Key (lato utente) / Computer Token (lato agente) |\n| Registrare un account utente | Nessuna (pubblico) |\n| Login | Nessuna (pubblico) |\n| Creare / elencare / eliminare menti | JWT |\n| Condividere una mente con un altro utente | JWT |\n| Sottoscrivere notifiche web push | JWT |\n| Vedere il log di audit | Mind Key |\n\n## La regola semplice\n\n> [!TIP]\n> **Se tocca i dati di una singola mente → Mind Key.**\n> **Se gestisce l'account o i metadati delle menti → JWT.**\n\n## Mind Key — token di accesso ai dati\n\nUna Mind Key concede accesso ai **dati di una mente**. È un token long-lived\nche non scade mai (fino a quando la mente viene eliminata). Perfetta per:\n\n- Agenti LLM che persistono memorie tra sessioni\n- Cron job in background\n- Configurazione del server MCP\n- Integrazioni webhook\n- App mobile che leggono la memoria\n\n### Cosa può fare la Mind Key\n\n- `GET /memory/recall` — leggere tutte le memorie in questa mente\n- `POST /memory` — memorizzare/aggiornare memorie\n- `GET /chat/poll` — leggere i messaggi chat\n- `POST /chat/reply` — inviare messaggi chat\n- `GET /mind/tasks` — elencare le attività\n- `POST /mind/task` — creare attività\n- `POST /script` — memorizzare script\n- `POST /webhooks` — registrare webhook\n- `POST /computers/:id/commands` — accodare comandi per computer\n\n### Cosa NON può fare la Mind Key\n\n- Creare / elencare / eliminare menti (serve JWT)\n- Condividere una mente con un altro utente (serve JWT)\n- Vedere le informazioni dell'account utente (serve JWT)\n- Sottoscrivere web push (serve JWT)\n\n## JWT — token di gestione account\n\nUn JWT autentica l'**account utente**. Scade dopo 7 giorni ed è usato per\noperazioni a livello di account che coprono più menti o coinvolgono altri\nutenti.\n\n### Cosa può fare il JWT\n\n- `POST /minds` — creare una nuova mente (restituisce una nuova Mind Key)\n- `GET /minds` — elencare tutte le menti di questo utente\n- `DELETE /minds/:id` — eliminare una mente\n- `POST /sharing` — condividere una mente con un altro utente\n- `POST /push/subscribe` — sottoscrivere notifiche web push\n- `GET /sharing` — elencare le condivisioni delle menti\n\n### Cosa NON può fare il JWT\n\n- Leggere / scrivere memorie (serve Mind Key)\n- Inviare messaggi chat (serve Mind Key)\n- Gestire attività (serve Mind Key)\n- Registrare webhook (serve Mind Key)\n\n## Caso speciale: Computer Token\n\nGli endpoint `/computers/me/*` (lato agente, per lo screen-remote-agent) usano\nun terzo tipo di token: il **Computer Token**. Questo token viene restituito da\n`POST /computers/register` quando si riscatta un codice di installazione, ed è\nspecifico per un computer registrato.\n\n| Endpoint | Auth |\n|----------|------|\n| `GET /computers/me/poll` | Computer Token |\n| `POST /computers/me/commands/:cid/result` | Computer Token |\n| `GET /computers/list` | Mind Key o JWT |\n| `POST /computers/:id/commands` | Mind Key o JWT |\n\n## Modelli comuni\n\n### Modello 1: agente LLM singolo\n\n1. Si registra una volta → ottiene JWT\n2. Crea una mente → ottiene Mind Key\n3. L'LLM usa la Mind Key per tutto\n\n### Modello 2: agente multi-progetto\n\n1. Si registra una volta → ottiene JWT\n2. Crea menti multiple (work, personal, project-x) → ottiene Mind Key multiple\n3. L'LLM carica Mind Key diverse in base al contesto\n\n### Modello 3: condivisione di team\n\n1. L'Utente A crea una mente → ottiene Mind Key A\n2. L'Utente A condivide con l'Utente B tramite JWT (`POST /sharing`)\n3. L'Utente B ora può accedere tramite il suo stesso JWT\n4. Per l'accesso LLM, l'Utente B deve creare la sua Mind Key (o usare quella di A)\n\n### Modello 4: server MCP\n\nI server MCP usano sempre la Mind Key (impostata tramite variabile env\n`SYNAPSE_MIND_KEY`). Un'istanza del server MCP = una mente. Per accesso\nmulti-mente, esegua più istanze MCP o implementi cambio mente lato client.\n\n## Sintesi dei formati dei token\n\n| Token | Formato | Esempio |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36 caratteri | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 caratteri | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Prossimi passi\n\n- [Autenticazione](/docs/getting-started/authentication) — guida auth completa\n- [User & Minds API](/docs/api/user) — endpoint protetti da JWT\n- [Memory API](/docs/api/memory) — endpoint protetti da Mind Key\n","content_html":"<h1>Mind Key vs JWT — quando usare quale?</h1>\n<p>Synapse ha due token di autenticazione. Scegliere quello sbagliato porta a\nerrori 401. Questa guida le dà un framework decisionale chiaro.</p>\n<h2>Tabella decisionale rapida</h2>\n<table>\n<thead>\n<tr>\n<th>Vuole...</th>\n<th>Usi</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Memorizzare / richiamare memorie</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Inviare / polling messaggi chat</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Gestire attività</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Memorizzare script</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Registrare webhook</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Controllare computer</td>\n<td>Mind Key (lato utente) / Computer Token (lato agente)</td>\n</tr>\n<tr>\n<td>Registrare un account utente</td>\n<td>Nessuna (pubblico)</td>\n</tr>\n<tr>\n<td>Login</td>\n<td>Nessuna (pubblico)</td>\n</tr>\n<tr>\n<td>Creare / elencare / eliminare menti</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Condividere una mente con un altro utente</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Sottoscrivere notifiche web push</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Vedere il log di audit</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>La regola semplice</h2>\n<div class=\"callout callout-ok\">**Se tocca i dati di una singola mente → Mind Key.**\n**Se gestisce l'account o i metadati delle menti → JWT.**</div><h2>Mind Key — token di accesso ai dati</h2>\n<p>Una Mind Key concede accesso ai <strong>dati di una mente</strong>. È un token long-lived\nche non scade mai (fino a quando la mente viene eliminata). Perfetta per:</p>\n<ul>\n<li>Agenti LLM che persistono memorie tra sessioni</li>\n<li>Cron job in background</li>\n<li>Configurazione del server MCP</li>\n<li>Integrazioni webhook</li>\n<li>App mobile che leggono la memoria</li>\n</ul>\n<h3>Cosa può fare la Mind Key</h3>\n<ul>\n<li><code>GET /memory/recall</code> — leggere tutte le memorie in questa mente</li>\n<li><code>POST /memory</code> — memorizzare/aggiornare memorie</li>\n<li><code>GET /chat/poll</code> — leggere i messaggi chat</li>\n<li><code>POST /chat/reply</code> — inviare messaggi chat</li>\n<li><code>GET /mind/tasks</code> — elencare le attività</li>\n<li><code>POST /mind/task</code> — creare attività</li>\n<li><code>POST /script</code> — memorizzare script</li>\n<li><code>POST /webhooks</code> — registrare webhook</li>\n<li><code>POST /computers/:id/commands</code> — accodare comandi per computer</li>\n</ul>\n<h3>Cosa NON può fare la Mind Key</h3>\n<ul>\n<li>Creare / elencare / eliminare menti (serve JWT)</li>\n<li>Condividere una mente con un altro utente (serve JWT)</li>\n<li>Vedere le informazioni dell&#39;account utente (serve JWT)</li>\n<li>Sottoscrivere web push (serve JWT)</li>\n</ul>\n<h2>JWT — token di gestione account</h2>\n<p>Un JWT autentica l&#39;<strong>account utente</strong>. Scade dopo 7 giorni ed è usato per\noperazioni a livello di account che coprono più menti o coinvolgono altri\nutenti.</p>\n<h3>Cosa può fare il JWT</h3>\n<ul>\n<li><code>POST /minds</code> — creare una nuova mente (restituisce una nuova Mind Key)</li>\n<li><code>GET /minds</code> — elencare tutte le menti di questo utente</li>\n<li><code>DELETE /minds/:id</code> — eliminare una mente</li>\n<li><code>POST /sharing</code> — condividere una mente con un altro utente</li>\n<li><code>POST /push/subscribe</code> — sottoscrivere notifiche web push</li>\n<li><code>GET /sharing</code> — elencare le condivisioni delle menti</li>\n</ul>\n<h3>Cosa NON può fare il JWT</h3>\n<ul>\n<li>Leggere / scrivere memorie (serve Mind Key)</li>\n<li>Inviare messaggi chat (serve Mind Key)</li>\n<li>Gestire attività (serve Mind Key)</li>\n<li>Registrare webhook (serve Mind Key)</li>\n</ul>\n<h2>Caso speciale: Computer Token</h2>\n<p>Gli endpoint <code>/computers/me/*</code> (lato agente, per lo screen-remote-agent) usano\nun terzo tipo di token: il <strong>Computer Token</strong>. Questo token viene restituito da\n<code>POST /computers/register</code> quando si riscatta un codice di installazione, ed è\nspecifico per un computer registrato.</p>\n<table>\n<thead>\n<tr>\n<th>Endpoint</th>\n<th>Auth</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /computers/me/poll</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>POST /computers/me/commands/:cid/result</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>GET /computers/list</code></td>\n<td>Mind Key o JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key o JWT</td>\n</tr>\n</tbody></table>\n<h2>Modelli comuni</h2>\n<h3>Modello 1: agente LLM singolo</h3>\n<ol>\n<li>Si registra una volta → ottiene JWT</li>\n<li>Crea una mente → ottiene Mind Key</li>\n<li>L&#39;LLM usa la Mind Key per tutto</li>\n</ol>\n<h3>Modello 2: agente multi-progetto</h3>\n<ol>\n<li>Si registra una volta → ottiene JWT</li>\n<li>Crea menti multiple (work, personal, project-x) → ottiene Mind Key multiple</li>\n<li>L&#39;LLM carica Mind Key diverse in base al contesto</li>\n</ol>\n<h3>Modello 3: condivisione di team</h3>\n<ol>\n<li>L&#39;Utente A crea una mente → ottiene Mind Key A</li>\n<li>L&#39;Utente A condivide con l&#39;Utente B tramite JWT (<code>POST /sharing</code>)</li>\n<li>L&#39;Utente B ora può accedere tramite il suo stesso JWT</li>\n<li>Per l&#39;accesso LLM, l&#39;Utente B deve creare la sua Mind Key (o usare quella di A)</li>\n</ol>\n<h3>Modello 4: server MCP</h3>\n<p>I server MCP usano sempre la Mind Key (impostata tramite variabile env\n<code>SYNAPSE_MIND_KEY</code>). Un&#39;istanza del server MCP = una mente. Per accesso\nmulti-mente, esegua più istanze MCP o implementi cambio mente lato client.</p>\n<h2>Sintesi dei formati dei token</h2>\n<table>\n<thead>\n<tr>\n<th>Token</th>\n<th>Formato</th>\n<th>Esempio</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key</td>\n<td><code>mk_</code> + 36 caratteri</td>\n<td><code>mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789</code></td>\n</tr>\n<tr>\n<td>JWT</td>\n<td><code>eyJ</code> + base64</td>\n<td><code>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</code></td>\n</tr>\n<tr>\n<td>Computer Token</td>\n<td><code>ct_</code> + 36 caratteri</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Prossimi passi</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Autenticazione</a> — guida auth completa</li>\n<li><a href=\"/docs/api/user\">User &amp; Minds API</a> — endpoint protetti da JWT</li>\n<li><a href=\"/docs/api/memory\">Memory API</a> — endpoint protetti da Mind Key</li>\n</ul>\n","urls":{"html":"/docs/getting-started/mind-key-vs-jwt","text":"/docs/getting-started/mind-key-vs-jwt?format=text","json":"/docs/getting-started/mind-key-vs-jwt?format=json","llm":"/docs/getting-started/mind-key-vs-jwt?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}