# Mind Key vs JWT — Wann Was?

Synapse hat zwei Authentifizierungs-Tokens. Die falsche Wahl führt zu 401-Fehlern.
Dieser Guide gibt dir einen klaren Entscheidungsrahmen.

## Schnelle Entscheidungs-Tabelle

| Du willst... | Verwende |
|---------------|----------|
| Memories speichern / abrufen | Mind Key |
| Chat-Nachrichten senden / abholen | Mind Key |
| Tasks verwalten | Mind Key |
| Scripts speichern | Mind Key |
| Webhooks registrieren | Mind Key |
| Rechner steuern | Mind Key (Nutzerseite) / Computer-Token (Agentenseite) |
| Nutzerkonto registrieren | Keins (öffentlich) |
| Einloggen | Keins (öffentlich) |
| Minds anlegen / auflisten / löschen | JWT |
| Mind mit anderem Nutzer teilen | JWT |
| Web-Push-Benachrichtigungen abonnieren | JWT |
| Audit-Log ansehen | Mind Key |

## Die einfache Regel

> [!TIP]
> **Wenn es die Daten eines einzelnen Minds berührt → Mind Key.**
> **Wenn es das Konto oder Mind-Metadaten verwaltet → JWT.**

## Mind Key — Datenzugriffs-Token

Ein Mind Key gewährt Zugriff auf **die Daten eines Minds**. Er ist ein
langlebiges Token, das nie abläuft (bis der Mind gelöscht wird). Perfekt für:

- LLM-Agenten, die Memories über Sessions persistieren
- Hintergrund-Cron-Jobs
- MCP-Server-Konfiguration
- Webhook-Integrationen
- Mobile Apps, die Memory lesen

### Was der Mind Key kann

- `GET /memory/recall` — alle Memories in diesem Mind lesen
- `POST /memory` — Memories speichern/aktualisieren
- `GET /chat/poll` — Chat-Nachrichten lesen
- `POST /chat/reply` — Chat-Nachrichten senden
- `GET /mind/tasks` — Tasks auflisten
- `POST /mind/task` — Tasks anlegen
- `POST /script` — Scripts speichern
- `POST /webhooks` — Webhooks registrieren
- `POST /computers/:id/commands` — Computer-Commands einreihen

### Was der Mind Key NICHT kann

- Minds anlegen / auflisten / löschen (braucht JWT)
- Mind mit anderem Nutzer teilen (braucht JWT)
- Nutzerkonto-Infos ansehen (braucht JWT)
- Web-Push abonnieren (braucht JWT)

## JWT — Kontoverwaltungs-Token

Ein JWT authentifiziert das **Nutzerkonto**. Es läuft nach 7 Tagen ab und wird
für Konto-Ebene-Operationen verwendet, die mehrere Minds umfassen oder andere
Nutzer involvieren.

### Was das JWT kann

- `POST /minds` — neuen Mind anlegen (liefert neuen Mind Key)
- `GET /minds` — alle Minds dieses Nutzers auflisten
- `DELETE /minds/:id` — Mind löschen
- `POST /sharing` — Mind mit anderem Nutzer teilen
- `POST /push/subscribe` — Web-Push-Benachrichtigungen abonnieren
- `GET /sharing` — Mind-Shares auflisten

### Was das JWT NICHT kann

- Memories lesen / schreiben (braucht Mind Key)
- Chat-Nachrichten senden (braucht Mind Key)
- Tasks verwalten (braucht Mind Key)
- Webhooks registrieren (braucht Mind Key)

## Sonderfall: Computer-Token

Die `/computers/me/*`-Endpunkte (agentenseitig, für den screen-remote-agent)
verwenden einen dritten Token-Typ: das **Computer-Token**. Dieses Token wird von
`POST /computers/register` beim Einlösen eines Installationscodes zurückgegeben
und ist spezifisch für einen registrierten Rechner.

| Endpunkt | Auth |
|----------|------|
| `GET /computers/me/poll` | Computer-Token |
| `POST /computers/me/commands/:cid/result` | Computer-Token |
| `GET /computers/list` | Mind Key oder JWT |
| `POST /computers/:id/commands` | Mind Key oder JWT |

## Häufige Patterns

### Pattern 1: Einzelner LLM-Agent

1. Einmal registrieren → JWT erhalten
2. Einen Mind anlegen → Mind Key erhalten
3. LLM verwendet Mind Key für alles

### Pattern 2: Multi-Projekt-Agent

1. Einmal registrieren → JWT erhalten
2. Mehrere Minds anlegen (work, personal, project-x) → mehrere Mind Keys erhalten
3. LLM lädt je nach Kontext unterschiedlichen Mind Key

### Pattern 3: Team-Sharing

1. Nutzer A legt Mind an → Mind Key A erhalten
2. Nutzer A teilt mit Nutzer B via JWT (`POST /sharing`)
3. Nutzer B kann nun über sein eigenes JWT zugreifen
4. Für LLM-Zugriff muss Nutzer B einen eigenen Mind Key anlegen (oder A's verwenden)

### Pattern 4: MCP-Server

MCP-Server verwenden immer Mind Key (via `SYNAPSE_MIND_KEY`-Env-Var gesetzt).
Eine MCP-Server-Instanz = ein Mind. Für Multi-Mind-Zugriff: mehrere MCP-
Instanzen betreiben oder Client-seitiges Mind-Switching implementieren.

## Token-Format-Spickzettel

| Token | Format | Beispiel |
|-------|--------|----------|
| Mind Key | `mk_` + 36 Zeichen | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer-Token | `ct_` + 36 Zeichen | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Nächste Schritte

- [Authentifizierung](/docs/getting-started/authentication) — vollständiger Auth-Guide
- [User- & Minds-API](/docs/api/user) — JWT-geschützte Endpunkte
- [Memory-API](/docs/api/memory) — Mind-Key-geschützte Endpunkte