# Authenticatie & Mind Keys

Synapse gebruikt twee authenticatiemethoden, elk geoptimaliseerd voor een ander doel.
Het verschil begrijpen is essentieel voor het bouwen van betrouwbare integraties.

## Twee auth-methoden

| Methode | Gebruik | Ratelimit | Verval |
|---------|---------|-----------|--------|
| **Mind Key** | LLM-agents, geautomatiseerde tools | Geen (header) / 60 per min (query) | Nooit |
| **JWT** | Mensgerichte UI, account-operaties | Geen | 7 dagen |

## Mind Key (voor agents)

Een Mind Key is een tenant-scoped API-token. Het authenticeert de data van één mind
(herinneringen, taken, chat, scripts, enz.). Gebruik het voor:

- LLM-agents die de API aanroepen
- Achtergrond-automatiseringsscripts
- MCP-server-configuratie
- Elke langlevende integratie

### Header-authenticatie (aanbevolen)

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

### Queryparameter (voor URL-only tools)

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

> [!WARNING]
> De `?key=`-queryparameter is gelimiteerd tot **60 verzoeken per minuut**.
> De Bearer-header heeft geen ratelimit. Gebruik de header wanneer uw client
> aangepaste headers ondersteunt.

### Een Mind Key aanmaken

```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"}'
```

De respons bevat `mind_key` — **sla deze onmiddellijk op**, deze wordt slechts één keer getoond.

### Uw minds tonen

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

### Een mind verwijderen (onomkeerbaar!)

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

## JWT (voor mensen)

JWT's authenticeren het **gebruikersaccount**, niet een specifieke mind. Gebruik ze voor:

- Accountregistratie en login
- Minds aanmaken/tonen/verwijderen
- Minds delen met andere gebruikers
- Web Push-abonnementsbeheer

### Registreren

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

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

### Inloggen

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

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

### JWT-verval

JWT's vervallen na **7 dagen**. Wanneer een JWT vervalt, roept u gewoon opnieuw `/login`
aan om een verse te krijgen. De Mind Key vervalt nooit, dus bestaande agent-integraties
blijven werken.

## Beveiligings-best-practices

> [!CRITICAL]
> - **Commit Mind Keys nooit naar git.** Gebruik omgevingsvariabelen.
> - **Log Mind Keys nooit.** Maskeer ze in logs (`mk_***...***xyz`).
> - **Roteer sleutels** bij vermoeden van een lek (verwijder de mind, maak een nieuwe aan).
> - **Gebruik één mind per project** om de schade bij een lek te beperken.

### Omgevingsvariabele-patroon

```bash
# .env (NOOIT dit bestand committen)
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-patroon

Elke gebruiker kan meerdere minds hebben. Veelvoorkomende patronen:

| Mind-naam | Doel |
|-----------|------|
| `work` | Werkgerelateerde herinneringen |
| `personal` | Persoonlijke voorkeuren, familie |
| `project-synapse` | Specifieke projectcontext |
| `learning-german` | Leervoortgang |
| `assistant-default` | Algemene fallback |

Gebruik verschillende Mind Keys voor verschillende LLM-sessies om contexten gescheiden te houden.

## Ratelimits

| Auth-methode | Limiet | Bereik |
|--------------|--------|--------|
| Mind Key (header) | Geen | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | Geen | Per-gebruiker |
| Openbare eindpunten | Geen | Globaal |

Ratelimit-headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)
worden in responsen opgenomen waar van toepassing.

## Volgende stappen

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — wanneer welke gebruiken
- [Memory API](/docs/api/memory) — wat u kunt doen met een Mind Key
- [User API](/docs/api/user) — accountbeheer met JWT's