{"title":"Mind Key vs JWT — Wann Was?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Entscheidungsleitfaden: Mind Key für Agent-Datenzugriff, JWT für Kontoverwaltung.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":619,"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":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Mind Key vs JWT — Wann Was?\n\nSynapse hat zwei Authentifizierungs-Tokens. Die falsche Wahl führt zu 401-Fehlern.\nDieser Guide gibt dir einen klaren Entscheidungsrahmen.\n\n## Schnelle Entscheidungs-Tabelle\n\n| Du willst... | Verwende |\n|---------------|----------|\n| Memories speichern / abrufen | Mind Key |\n| Chat-Nachrichten senden / abholen | Mind Key |\n| Tasks verwalten | Mind Key |\n| Scripts speichern | Mind Key |\n| Webhooks registrieren | Mind Key |\n| Rechner steuern | Mind Key (Nutzerseite) / Computer-Token (Agentenseite) |\n| Nutzerkonto registrieren | Keins (öffentlich) |\n| Einloggen | Keins (öffentlich) |\n| Minds anlegen / auflisten / löschen | JWT |\n| Mind mit anderem Nutzer teilen | JWT |\n| Web-Push-Benachrichtigungen abonnieren | JWT |\n| Audit-Log ansehen | Mind Key |\n\n## Die einfache Regel\n\n> [!TIP]\n> **Wenn es die Daten eines einzelnen Minds berührt → Mind Key.**\n> **Wenn es das Konto oder Mind-Metadaten verwaltet → JWT.**\n\n## Mind Key — Datenzugriffs-Token\n\nEin Mind Key gewährt Zugriff auf **die Daten eines Minds**. Er ist ein\nlanglebiges Token, das nie abläuft (bis der Mind gelöscht wird). Perfekt für:\n\n- LLM-Agenten, die Memories über Sessions persistieren\n- Hintergrund-Cron-Jobs\n- MCP-Server-Konfiguration\n- Webhook-Integrationen\n- Mobile Apps, die Memory lesen\n\n### Was der Mind Key kann\n\n- `GET /memory/recall` — alle Memories in diesem Mind lesen\n- `POST /memory` — Memories speichern/aktualisieren\n- `GET /chat/poll` — Chat-Nachrichten lesen\n- `POST /chat/reply` — Chat-Nachrichten senden\n- `GET /mind/tasks` — Tasks auflisten\n- `POST /mind/task` — Tasks anlegen\n- `POST /script` — Scripts speichern\n- `POST /webhooks` — Webhooks registrieren\n- `POST /computers/:id/commands` — Computer-Commands einreihen\n\n### Was der Mind Key NICHT kann\n\n- Minds anlegen / auflisten / löschen (braucht JWT)\n- Mind mit anderem Nutzer teilen (braucht JWT)\n- Nutzerkonto-Infos ansehen (braucht JWT)\n- Web-Push abonnieren (braucht JWT)\n\n## JWT — Kontoverwaltungs-Token\n\nEin JWT authentifiziert das **Nutzerkonto**. Es läuft nach 7 Tagen ab und wird\nfür Konto-Ebene-Operationen verwendet, die mehrere Minds umfassen oder andere\nNutzer involvieren.\n\n### Was das JWT kann\n\n- `POST /minds` — neuen Mind anlegen (liefert neuen Mind Key)\n- `GET /minds` — alle Minds dieses Nutzers auflisten\n- `DELETE /minds/:id` — Mind löschen\n- `POST /sharing` — Mind mit anderem Nutzer teilen\n- `POST /push/subscribe` — Web-Push-Benachrichtigungen abonnieren\n- `GET /sharing` — Mind-Shares auflisten\n\n### Was das JWT NICHT kann\n\n- Memories lesen / schreiben (braucht Mind Key)\n- Chat-Nachrichten senden (braucht Mind Key)\n- Tasks verwalten (braucht Mind Key)\n- Webhooks registrieren (braucht Mind Key)\n\n## Sonderfall: Computer-Token\n\nDie `/computers/me/*`-Endpunkte (agentenseitig, für den screen-remote-agent)\nverwenden einen dritten Token-Typ: das **Computer-Token**. Dieses Token wird von\n`POST /computers/register` beim Einlösen eines Installationscodes zurückgegeben\nund ist spezifisch für einen registrierten Rechner.\n\n| Endpunkt | Auth |\n|----------|------|\n| `GET /computers/me/poll` | Computer-Token |\n| `POST /computers/me/commands/:cid/result` | Computer-Token |\n| `GET /computers/list` | Mind Key oder JWT |\n| `POST /computers/:id/commands` | Mind Key oder JWT |\n\n## Häufige Patterns\n\n### Pattern 1: Einzelner LLM-Agent\n\n1. Einmal registrieren → JWT erhalten\n2. Einen Mind anlegen → Mind Key erhalten\n3. LLM verwendet Mind Key für alles\n\n### Pattern 2: Multi-Projekt-Agent\n\n1. Einmal registrieren → JWT erhalten\n2. Mehrere Minds anlegen (work, personal, project-x) → mehrere Mind Keys erhalten\n3. LLM lädt je nach Kontext unterschiedlichen Mind Key\n\n### Pattern 3: Team-Sharing\n\n1. Nutzer A legt Mind an → Mind Key A erhalten\n2. Nutzer A teilt mit Nutzer B via JWT (`POST /sharing`)\n3. Nutzer B kann nun über sein eigenes JWT zugreifen\n4. Für LLM-Zugriff muss Nutzer B einen eigenen Mind Key anlegen (oder A's verwenden)\n\n### Pattern 4: MCP-Server\n\nMCP-Server verwenden immer Mind Key (via `SYNAPSE_MIND_KEY`-Env-Var gesetzt).\nEine MCP-Server-Instanz = ein Mind. Für Multi-Mind-Zugriff: mehrere MCP-\nInstanzen betreiben oder Client-seitiges Mind-Switching implementieren.\n\n## Token-Format-Spickzettel\n\n| Token | Format | Beispiel |\n|-------|--------|----------|\n| Mind Key | `mk_` + 36 Zeichen | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer-Token | `ct_` + 36 Zeichen | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Nächste Schritte\n\n- [Authentifizierung](/docs/getting-started/authentication) — vollständiger Auth-Guide\n- [User- & Minds-API](/docs/api/user) — JWT-geschützte Endpunkte\n- [Memory-API](/docs/api/memory) — Mind-Key-geschützte Endpunkte\n","content_html":"<h1>Mind Key vs JWT — Wann Was?</h1>\n<p>Synapse hat zwei Authentifizierungs-Tokens. Die falsche Wahl führt zu 401-Fehlern.\nDieser Guide gibt dir einen klaren Entscheidungsrahmen.</p>\n<h2>Schnelle Entscheidungs-Tabelle</h2>\n<table>\n<thead>\n<tr>\n<th>Du willst...</th>\n<th>Verwende</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Memories speichern / abrufen</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Chat-Nachrichten senden / abholen</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Tasks verwalten</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Scripts speichern</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Webhooks registrieren</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Rechner steuern</td>\n<td>Mind Key (Nutzerseite) / Computer-Token (Agentenseite)</td>\n</tr>\n<tr>\n<td>Nutzerkonto registrieren</td>\n<td>Keins (öffentlich)</td>\n</tr>\n<tr>\n<td>Einloggen</td>\n<td>Keins (öffentlich)</td>\n</tr>\n<tr>\n<td>Minds anlegen / auflisten / löschen</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Mind mit anderem Nutzer teilen</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Web-Push-Benachrichtigungen abonnieren</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Audit-Log ansehen</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>Die einfache Regel</h2>\n<div class=\"callout callout-ok\">**Wenn es die Daten eines einzelnen Minds berührt → Mind Key.**\n**Wenn es das Konto oder Mind-Metadaten verwaltet → JWT.**</div><h2>Mind Key — Datenzugriffs-Token</h2>\n<p>Ein Mind Key gewährt Zugriff auf <strong>die Daten eines Minds</strong>. Er ist ein\nlanglebiges Token, das nie abläuft (bis der Mind gelöscht wird). Perfekt für:</p>\n<ul>\n<li>LLM-Agenten, die Memories über Sessions persistieren</li>\n<li>Hintergrund-Cron-Jobs</li>\n<li>MCP-Server-Konfiguration</li>\n<li>Webhook-Integrationen</li>\n<li>Mobile Apps, die Memory lesen</li>\n</ul>\n<h3>Was der Mind Key kann</h3>\n<ul>\n<li><code>GET /memory/recall</code> — alle Memories in diesem Mind lesen</li>\n<li><code>POST /memory</code> — Memories speichern/aktualisieren</li>\n<li><code>GET /chat/poll</code> — Chat-Nachrichten lesen</li>\n<li><code>POST /chat/reply</code> — Chat-Nachrichten senden</li>\n<li><code>GET /mind/tasks</code> — Tasks auflisten</li>\n<li><code>POST /mind/task</code> — Tasks anlegen</li>\n<li><code>POST /script</code> — Scripts speichern</li>\n<li><code>POST /webhooks</code> — Webhooks registrieren</li>\n<li><code>POST /computers/:id/commands</code> — Computer-Commands einreihen</li>\n</ul>\n<h3>Was der Mind Key NICHT kann</h3>\n<ul>\n<li>Minds anlegen / auflisten / löschen (braucht JWT)</li>\n<li>Mind mit anderem Nutzer teilen (braucht JWT)</li>\n<li>Nutzerkonto-Infos ansehen (braucht JWT)</li>\n<li>Web-Push abonnieren (braucht JWT)</li>\n</ul>\n<h2>JWT — Kontoverwaltungs-Token</h2>\n<p>Ein JWT authentifiziert das <strong>Nutzerkonto</strong>. Es läuft nach 7 Tagen ab und wird\nfür Konto-Ebene-Operationen verwendet, die mehrere Minds umfassen oder andere\nNutzer involvieren.</p>\n<h3>Was das JWT kann</h3>\n<ul>\n<li><code>POST /minds</code> — neuen Mind anlegen (liefert neuen Mind Key)</li>\n<li><code>GET /minds</code> — alle Minds dieses Nutzers auflisten</li>\n<li><code>DELETE /minds/:id</code> — Mind löschen</li>\n<li><code>POST /sharing</code> — Mind mit anderem Nutzer teilen</li>\n<li><code>POST /push/subscribe</code> — Web-Push-Benachrichtigungen abonnieren</li>\n<li><code>GET /sharing</code> — Mind-Shares auflisten</li>\n</ul>\n<h3>Was das JWT NICHT kann</h3>\n<ul>\n<li>Memories lesen / schreiben (braucht Mind Key)</li>\n<li>Chat-Nachrichten senden (braucht Mind Key)</li>\n<li>Tasks verwalten (braucht Mind Key)</li>\n<li>Webhooks registrieren (braucht Mind Key)</li>\n</ul>\n<h2>Sonderfall: Computer-Token</h2>\n<p>Die <code>/computers/me/*</code>-Endpunkte (agentenseitig, für den screen-remote-agent)\nverwenden einen dritten Token-Typ: das <strong>Computer-Token</strong>. Dieses Token wird von\n<code>POST /computers/register</code> beim Einlösen eines Installationscodes zurückgegeben\nund ist spezifisch für einen registrierten Rechner.</p>\n<table>\n<thead>\n<tr>\n<th>Endpunkt</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 oder JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key oder JWT</td>\n</tr>\n</tbody></table>\n<h2>Häufige Patterns</h2>\n<h3>Pattern 1: Einzelner LLM-Agent</h3>\n<ol>\n<li>Einmal registrieren → JWT erhalten</li>\n<li>Einen Mind anlegen → Mind Key erhalten</li>\n<li>LLM verwendet Mind Key für alles</li>\n</ol>\n<h3>Pattern 2: Multi-Projekt-Agent</h3>\n<ol>\n<li>Einmal registrieren → JWT erhalten</li>\n<li>Mehrere Minds anlegen (work, personal, project-x) → mehrere Mind Keys erhalten</li>\n<li>LLM lädt je nach Kontext unterschiedlichen Mind Key</li>\n</ol>\n<h3>Pattern 3: Team-Sharing</h3>\n<ol>\n<li>Nutzer A legt Mind an → Mind Key A erhalten</li>\n<li>Nutzer A teilt mit Nutzer B via JWT (<code>POST /sharing</code>)</li>\n<li>Nutzer B kann nun über sein eigenes JWT zugreifen</li>\n<li>Für LLM-Zugriff muss Nutzer B einen eigenen Mind Key anlegen (oder A&#39;s verwenden)</li>\n</ol>\n<h3>Pattern 4: MCP-Server</h3>\n<p>MCP-Server verwenden immer Mind Key (via <code>SYNAPSE_MIND_KEY</code>-Env-Var gesetzt).\nEine MCP-Server-Instanz = ein Mind. Für Multi-Mind-Zugriff: mehrere MCP-\nInstanzen betreiben oder Client-seitiges Mind-Switching implementieren.</p>\n<h2>Token-Format-Spickzettel</h2>\n<table>\n<thead>\n<tr>\n<th>Token</th>\n<th>Format</th>\n<th>Beispiel</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key</td>\n<td><code>mk_</code> + 36 Zeichen</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 Zeichen</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Nächste Schritte</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Authentifizierung</a> — vollständiger Auth-Guide</li>\n<li><a href=\"/docs/api/user\">User- &amp; Minds-API</a> — JWT-geschützte Endpunkte</li>\n<li><a href=\"/docs/api/memory\">Memory-API</a> — Mind-Key-geschützte Endpunkte</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"]}