{"title":"Mind Key vs JWT — What When?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Decision guide: Mind Key for agent data access, JWT for account management.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":683,"read_minutes":3,"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":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Mind Key vs JWT — What When?\n\nSynapse has two authentication tokens. Choosing the wrong one leads to 401 errors.\nThis guide gives you a clear decision framework.\n\n## Quick Decision Table\n\n| You want to... | Use |\n|----------------|-----|\n| Store / recall memories | Mind Key |\n| Send / poll chat messages | Mind Key |\n| Manage tasks | Mind Key |\n| Store scripts | Mind Key |\n| Register webhooks | Mind Key |\n| Control computers | Mind Key (user-side) / Computer Token (agent-side) |\n| Register a user account | None (public) |\n| Login | None (public) |\n| Create / list / delete minds | JWT |\n| Share a mind with another user | JWT |\n| Subscribe to web push notifications | JWT |\n| View audit log | Mind Key |\n\n## The Simple Rule\n\n> [!TIP]\n> **If it touches a single mind's data → Mind Key.**\n> **If it manages the account or mind metadata → JWT.**\n\n## Mind Key — Data Access Token\n\nA Mind Key grants access to **one mind's data**. It's a long-lived token that\nnever expires (until the mind is deleted). Perfect for:\n\n- LLM agents persisting memories across sessions\n- Background cron jobs\n- MCP server configuration\n- Webhook integrations\n- Mobile apps reading memory\n\n### What Mind Key can do\n\n- `GET /memory/recall` — read all memories in this mind\n- `POST /memory` — store/update memories\n- `GET /chat/poll` — read chat messages\n- `POST /chat/reply` — send chat messages\n- `GET /mind/tasks` — list tasks\n- `POST /mind/task` — create tasks\n- `POST /script` — store scripts\n- `POST /webhooks` — register webhooks\n- `POST /computers/:id/commands` — queue computer commands\n\n### What Mind Key CANNOT do\n\n- Create / list / delete minds (need JWT)\n- Share mind with another user (need JWT)\n- View user account info (need JWT)\n- Subscribe to web push (need JWT)\n\n## JWT — Account Management Token\n\nA JWT authenticates the **user account**. It expires after 7 days and is used\nfor account-level operations that span multiple minds or involve other users.\n\n### What JWT can do\n\n- `POST /minds` — create a new mind (returns a new Mind Key)\n- `GET /minds` — list all minds for this user\n- `DELETE /minds/:id` — delete a mind\n- `POST /sharing` — share a mind with another user\n- `POST /push/subscribe` — subscribe to web push notifications\n- `GET /sharing` — list mind shares\n\n### What JWT CANNOT do\n\n- Read / write memories (need Mind Key)\n- Send chat messages (need Mind Key)\n- Manage tasks (need Mind Key)\n- Register webhooks (need Mind Key)\n\n## Special Case: Computer Token\n\nThe `/computers/me/*` endpoints (agent-facing, for the screen-remote-agent)\nuse a third token type: the **Computer Token**. This token is returned by\n`POST /computers/register` when redeeming an install code, and is specific to\none registered computer.\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 or JWT |\n| `POST /computers/:id/commands` | Mind Key or JWT |\n\n## Common Patterns\n\n### Pattern 1: Single LLM Agent\n\n1. Register once → get JWT\n2. Create one mind → get Mind Key\n3. LLM uses Mind Key for everything\n\n### Pattern 2: Multi-Project Agent\n\n1. Register once → get JWT\n2. Create multiple minds (work, personal, project-x) → get multiple Mind Keys\n3. LLM loads different Mind Key based on context\n\n### Pattern 3: Team Sharing\n\n1. User A creates a mind → gets Mind Key A\n2. User A shares with User B via JWT (`POST /sharing`)\n3. User B can now access via their own JWT\n4. For LLM access, User B needs to create their own Mind Key (or use A's)\n\n### Pattern 4: MCP Server\n\nMCP servers always use Mind Key (set via `SYNAPSE_MIND_KEY` env var). One MCP\nserver instance = one mind. For multi-mind access, run multiple MCP instances\nor implement client-side mind switching.\n\n## Token Format Cheat Sheet\n\n| Token | Format | Example |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36 chars | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 chars | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Next Steps\n\n- [Authentication](/docs/getting-started/authentication) — full auth guide\n- [User & Minds API](/docs/api/user) — JWT-protected endpoints\n- [Memory API](/docs/api/memory) — Mind Key-protected endpoints\n","content_html":"<h1>Mind Key vs JWT — What When?</h1>\n<p>Synapse has two authentication tokens. Choosing the wrong one leads to 401 errors.\nThis guide gives you a clear decision framework.</p>\n<h2>Quick Decision Table</h2>\n<table>\n<thead>\n<tr>\n<th>You want to...</th>\n<th>Use</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Store / recall memories</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Send / poll chat messages</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Manage tasks</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Store scripts</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Register webhooks</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Control computers</td>\n<td>Mind Key (user-side) / Computer Token (agent-side)</td>\n</tr>\n<tr>\n<td>Register a user account</td>\n<td>None (public)</td>\n</tr>\n<tr>\n<td>Login</td>\n<td>None (public)</td>\n</tr>\n<tr>\n<td>Create / list / delete minds</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Share a mind with another user</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Subscribe to web push notifications</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>View audit log</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>The Simple Rule</h2>\n<div class=\"callout callout-ok\">**If it touches a single mind's data → Mind Key.**\n**If it manages the account or mind metadata → JWT.**</div><h2>Mind Key — Data Access Token</h2>\n<p>A Mind Key grants access to <strong>one mind&#39;s data</strong>. It&#39;s a long-lived token that\nnever expires (until the mind is deleted). Perfect for:</p>\n<ul>\n<li>LLM agents persisting memories across sessions</li>\n<li>Background cron jobs</li>\n<li>MCP server configuration</li>\n<li>Webhook integrations</li>\n<li>Mobile apps reading memory</li>\n</ul>\n<h3>What Mind Key can do</h3>\n<ul>\n<li><code>GET /memory/recall</code> — read all memories in this mind</li>\n<li><code>POST /memory</code> — store/update memories</li>\n<li><code>GET /chat/poll</code> — read chat messages</li>\n<li><code>POST /chat/reply</code> — send chat messages</li>\n<li><code>GET /mind/tasks</code> — list tasks</li>\n<li><code>POST /mind/task</code> — create tasks</li>\n<li><code>POST /script</code> — store scripts</li>\n<li><code>POST /webhooks</code> — register webhooks</li>\n<li><code>POST /computers/:id/commands</code> — queue computer commands</li>\n</ul>\n<h3>What Mind Key CANNOT do</h3>\n<ul>\n<li>Create / list / delete minds (need JWT)</li>\n<li>Share mind with another user (need JWT)</li>\n<li>View user account info (need JWT)</li>\n<li>Subscribe to web push (need JWT)</li>\n</ul>\n<h2>JWT — Account Management Token</h2>\n<p>A JWT authenticates the <strong>user account</strong>. It expires after 7 days and is used\nfor account-level operations that span multiple minds or involve other users.</p>\n<h3>What JWT can do</h3>\n<ul>\n<li><code>POST /minds</code> — create a new mind (returns a new Mind Key)</li>\n<li><code>GET /minds</code> — list all minds for this user</li>\n<li><code>DELETE /minds/:id</code> — delete a mind</li>\n<li><code>POST /sharing</code> — share a mind with another user</li>\n<li><code>POST /push/subscribe</code> — subscribe to web push notifications</li>\n<li><code>GET /sharing</code> — list mind shares</li>\n</ul>\n<h3>What JWT CANNOT do</h3>\n<ul>\n<li>Read / write memories (need Mind Key)</li>\n<li>Send chat messages (need Mind Key)</li>\n<li>Manage tasks (need Mind Key)</li>\n<li>Register webhooks (need Mind Key)</li>\n</ul>\n<h2>Special Case: Computer Token</h2>\n<p>The <code>/computers/me/*</code> endpoints (agent-facing, for the screen-remote-agent)\nuse a third token type: the <strong>Computer Token</strong>. This token is returned by\n<code>POST /computers/register</code> when redeeming an install code, and is specific to\none registered computer.</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 or JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key or JWT</td>\n</tr>\n</tbody></table>\n<h2>Common Patterns</h2>\n<h3>Pattern 1: Single LLM Agent</h3>\n<ol>\n<li>Register once → get JWT</li>\n<li>Create one mind → get Mind Key</li>\n<li>LLM uses Mind Key for everything</li>\n</ol>\n<h3>Pattern 2: Multi-Project Agent</h3>\n<ol>\n<li>Register once → get JWT</li>\n<li>Create multiple minds (work, personal, project-x) → get multiple Mind Keys</li>\n<li>LLM loads different Mind Key based on context</li>\n</ol>\n<h3>Pattern 3: Team Sharing</h3>\n<ol>\n<li>User A creates a mind → gets Mind Key A</li>\n<li>User A shares with User B via JWT (<code>POST /sharing</code>)</li>\n<li>User B can now access via their own JWT</li>\n<li>For LLM access, User B needs to create their own Mind Key (or use A&#39;s)</li>\n</ol>\n<h3>Pattern 4: MCP Server</h3>\n<p>MCP servers always use Mind Key (set via <code>SYNAPSE_MIND_KEY</code> env var). One MCP\nserver instance = one mind. For multi-mind access, run multiple MCP instances\nor implement client-side mind switching.</p>\n<h2>Token Format Cheat Sheet</h2>\n<table>\n<thead>\n<tr>\n<th>Token</th>\n<th>Format</th>\n<th>Example</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key</td>\n<td><code>mk_</code> + 36 chars</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 chars</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Next Steps</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Authentication</a> — full auth guide</li>\n<li><a href=\"/docs/api/user\">User &amp; Minds API</a> — JWT-protected endpoints</li>\n<li><a href=\"/docs/api/memory\">Memory API</a> — Mind Key-protected endpoints</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"]}