# Authentifizierung & Mind Keys

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

## Zwei Auth-Methoden

| Methode | Anwendungsfall | Rate Limit | Ablauf |
|---------|----------------|------------|--------|
| **Mind Key** | LLM-Agenten, automatisierte Tools | Keins (Header) / 60 min (Query) | Nie |
| **JWT** | Human-UI, Konto-Operationen | Keins | 7 Tage |

## Mind Key (für Agenten)

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

- LLM-Agenten, die die API aufrufen
- Hintergrund-Automatisierungs-Scripts
- MCP-Server-Konfiguration
- Jede langlebige Integration

### Header-Authentifizierung (empfohlen)

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

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

```bash
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
```

> [!WARNING]
> Der `?key=`-Query-Parameter ist auf **60 Requests pro Minute** begrenzt.
> Der Bearer-Header hat kein Rate Limit. Verwende den Header, wenn dein Client
> eigene Header unterstützt.

### Einen Mind Key anlegen

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

Die Antwort enthält `mind_key` — **sofort speichern**, er wird nur einmal
angezeigt.

### Deine Minds auflisten

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

### Einen Mind löschen (unumkehrbar!)

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

## JWT (für Menschen)

JWTs authentifizieren das **Nutzerkonto**, nicht einen spezifischen Mind.
Verwende sie für:

- Konto-Registrierung und Login
- Minds anlegen / auflisten / löschen
- Minds mit anderen Nutzern teilen
- Web-Push-Abonnement-Verwaltung

### Registrieren

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

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

### Einloggen

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

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

### JWT-Ablauf

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

## Security-Best-Practices

> [!CRITICAL]
> - **Mind Keys niemals in Git committen.** Verwende Environment-Variablen.
> - **Mind Keys niemals loggen.** In Logs maskieren (`mk_***...***xyz`).
> - **Keys rotieren** bei Verdacht auf Leak (Mind löschen, neuen anlegen).
> - **Ein Mind pro Projekt**, um den Schadensradius bei geleaktem Key zu begrenzen.

### Environment-Variablen-Pattern

```bash
# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone
```

```typescript
// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});
```

### MCP-Server-Config

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

## Multi-Mind-Pattern

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

| Mind-Name | Zweck |
|-----------|-------|
| `work` | Job-bezogene Memories |
| `personal` | Persönliche Präferenzen, Familie |
| `project-synapse` | Spezifischer Projekt-Kontext |
| `learning-german` | Lernfortschritt |
| `assistant-default` | Allzweck-Fallback |

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

## Rate Limits

| Auth-Methode | Limit | Scope |
|---------------|-------|-------|
| Mind Key (Header) | Keins | Pro-Mind |
| Mind Key (?key=) | 60/min | Pro-IP |
| JWT (Header) | Keins | Pro-Nutzer |
| Öffentliche Endpunkte | Keins | Global |

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

## Nächste Schritte

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — wann was verwenden
- [Memory-API](/docs/api/memory) — was du mit einem Mind Key tun kannst
- [User-API](/docs/api/user) — Kontoverwaltung mit JWTs