{"title":"Authentifizierung & Mind Keys","slug":"authentication","category":"getting-started","summary":"Wie die Synapse-Authentifizierung funktioniert: Mind Keys für Agenten, JWTs für Menschen, ?key= für reine URL-Tools.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":433,"read_minutes":2,"llm_context":"Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).\nMind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)\nJWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)\nMind Key is shown only once at creation. Store it permanently.\nEach mind has exactly one Mind Key. Multiple minds = multiple keys.\n","lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Authentifizierung & Mind Keys\n\nSynapse verwendet zwei Authentifizierungsmethoden, jede für einen anderen\nAnwendungsfall optimiert. Den Unterschied zu verstehen ist essenziell für\nzuverlässige Integrationen.\n\n## Zwei Auth-Methoden\n\n| Methode | Anwendungsfall | Rate Limit | Ablauf |\n|---------|----------------|------------|--------|\n| **Mind Key** | LLM-Agenten, automatisierte Tools | Keins (Header) / 60 min (Query) | Nie |\n| **JWT** | Human-UI, Konto-Operationen | Keins | 7 Tage |\n\n## Mind Key (für Agenten)\n\nEin Mind Key ist ein Tenant-scoped API-Token. Er authentifiziert die Daten\neines einzelnen Minds (Memories, Tasks, Chat, Scripts etc.). Verwende ihn für:\n\n- LLM-Agenten, die die API aufrufen\n- Hintergrund-Automatisierungs-Scripts\n- MCP-Server-Konfiguration\n- Jede langlebige Integration\n\n### Header-Authentifizierung (empfohlen)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Query-Parameter (für reine URL-Tools)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Der `?key=`-Query-Parameter ist auf **60 Requests pro Minute** begrenzt.\n> Der Bearer-Header hat kein Rate Limit. Verwende den Header, wenn dein Client\n> eigene Header unterstützt.\n\n### Einen Mind Key anlegen\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/minds \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Work Mind\", \"description\": \"Project memories\"}'\n```\n\nDie Antwort enthält `mind_key` — **sofort speichern**, er wird nur einmal\nangezeigt.\n\n### Deine Minds auflisten\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Einen Mind löschen (unumkehrbar!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (für Menschen)\n\nJWTs authentifizieren das **Nutzerkonto**, nicht einen spezifischen Mind.\nVerwende sie für:\n\n- Konto-Registrierung und Login\n- Minds anlegen / auflisten / löschen\n- Minds mit anderen Nutzern teilen\n- Web-Push-Abonnement-Verwaltung\n\n### Registrieren\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nLiefert: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Einloggen\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nLiefert: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### JWT-Ablauf\n\nJWTs laufen nach **7 Tagen** ab. Wenn ein JWT abläuft, rufe einfach wieder\n`/login` auf, um ein frisches zu erhalten. Der Mind Key läuft nie ab, daher\nfunktionieren bestehende Agent-Integrationen weiter.\n\n## Security-Best-Practices\n\n> [!CRITICAL]\n> - **Mind Keys niemals in Git committen.** Verwende Environment-Variablen.\n> - **Mind Keys niemals loggen.** In Logs maskieren (`mk_***...***xyz`).\n> - **Keys rotieren** bei Verdacht auf Leak (Mind löschen, neuen anlegen).\n> - **Ein Mind pro Projekt**, um den Schadensradius bei geleaktem Key zu begrenzen.\n\n### Environment-Variablen-Pattern\n\n```bash\n# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone\n```\n\n```typescript\n// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n headers: { Authorization: `Bearer ${mindKey}` },\n});\n```\n\n### MCP-Server-Config\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_yourMindKeyHere\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n## Multi-Mind-Pattern\n\nJeder Nutzer kann mehrere Minds haben. Häufige Patterns:\n\n| Mind-Name | Zweck |\n|-----------|-------|\n| `work` | Job-bezogene Memories |\n| `personal` | Persönliche Präferenzen, Familie |\n| `project-synapse` | Spezifischer Projekt-Kontext |\n| `learning-german` | Lernfortschritt |\n| `assistant-default` | Allzweck-Fallback |\n\nVerwende in verschiedenen LLM-Sessions unterschiedliche Mind Keys, um Kontexte\ngetrennt zu halten.\n\n## Rate Limits\n\n| Auth-Methode | Limit | Scope |\n|---------------|-------|-------|\n| Mind Key (Header) | Keins | Pro-Mind |\n| Mind Key (?key=) | 60/min | Pro-IP |\n| JWT (Header) | Keins | Pro-Nutzer |\n| Öffentliche Endpunkte | Keins | Global |\n\nRate-Limit-Header (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)\nwerden bei Bedarf in Antworten mitgeliefert.\n\n## Nächste Schritte\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — wann was verwenden\n- [Memory-API](/docs/api/memory) — was du mit einem Mind Key tun kannst\n- [User-API](/docs/api/user) — Kontoverwaltung mit JWTs\n","content_html":"

Authentifizierung & Mind Keys

\n

Synapse verwendet zwei Authentifizierungsmethoden, jede für einen anderen\nAnwendungsfall optimiert. Den Unterschied zu verstehen ist essenziell für\nzuverlässige Integrationen.

\n

Zwei Auth-Methoden

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MethodeAnwendungsfallRate LimitAblauf
Mind KeyLLM-Agenten, automatisierte ToolsKeins (Header) / 60 min (Query)Nie
JWTHuman-UI, Konto-OperationenKeins7 Tage
\n

Mind Key (für Agenten)

\n

Ein Mind Key ist ein Tenant-scoped API-Token. Er authentifiziert die Daten\neines einzelnen Minds (Memories, Tasks, Chat, Scripts etc.). Verwende ihn für:

\n\n

Header-Authentifizierung (empfohlen)

\n
curl -H "Authorization: Bearer mk_yourMindKeyHere" \\\n     https://synapse.schaefer.zone/memory/recall

Query-Parameter (für reine URL-Tools)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
Der `?key=`-Query-Parameter ist auf **60 Requests pro Minute** begrenzt.\nDer Bearer-Header hat kein Rate Limit. Verwende den Header, wenn dein Client\neigene Header unterstützt.

Einen Mind Key anlegen

\n
curl -X POST https://synapse.schaefer.zone/minds \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"name": "Work Mind", "description": "Project memories"}'

Die Antwort enthält mind_key — sofort speichern, er wird nur einmal\nangezeigt.

\n

Deine Minds auflisten

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds

Einen Mind löschen (unumkehrbar!)

\n
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds/m_xyz789

JWT (für Menschen)

\n

JWTs authentifizieren das Nutzerkonto, nicht einen spezifischen Mind.\nVerwende sie für:

\n\n

Registrieren

\n
curl -X POST https://synapse.schaefer.zone/register \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Liefert: { "jwt": "eyJ...", "user": {...} }

\n

Einloggen

\n
curl -X POST https://synapse.schaefer.zone/login \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Liefert: { "jwt": "eyJ...", "user": {...} }

\n

JWT-Ablauf

\n

JWTs laufen nach 7 Tagen ab. Wenn ein JWT abläuft, rufe einfach wieder\n/login auf, um ein frisches zu erhalten. Der Mind Key läuft nie ab, daher\nfunktionieren bestehende Agent-Integrationen weiter.

\n

Security-Best-Practices

\n

Environment-Variablen-Pattern

\n
# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone
// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n  headers: { Authorization: `Bearer ${mindKey}` },\n});

MCP-Server-Config

\n
{\n  "mcpServers": {\n    "synapse": {\n      "command": "npx",\n      "args": ["-y", "synapse-mcp-api@latest"],\n      "env": {\n        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",\n        "SYNAPSE_URL": "https://synapse.schaefer.zone"\n      }\n    }\n  }\n}

Multi-Mind-Pattern

\n

Jeder Nutzer kann mehrere Minds haben. Häufige Patterns:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Mind-NameZweck
workJob-bezogene Memories
personalPersönliche Präferenzen, Familie
project-synapseSpezifischer Projekt-Kontext
learning-germanLernfortschritt
assistant-defaultAllzweck-Fallback
\n

Verwende in verschiedenen LLM-Sessions unterschiedliche Mind Keys, um Kontexte\ngetrennt zu halten.

\n

Rate Limits

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Auth-MethodeLimitScope
Mind Key (Header)KeinsPro-Mind
Mind Key (?key=)60/minPro-IP
JWT (Header)KeinsPro-Nutzer
Öffentliche EndpunkteKeinsGlobal
\n

Rate-Limit-Header (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After)\nwerden bei Bedarf in Antworten mitgeliefert.

\n

Nächste Schritte

\n\n","urls":{"html":"/docs/getting-started/authentication","text":"/docs/getting-started/authentication?format=text","json":"/docs/getting-started/authentication?format=json","llm":"/docs/getting-started/authentication?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}