# Autoryzacja i Mind Key

Synapse używa dwóch metod autoryzacji, każda zoptymalizowana pod inny przypadek.
Zrozumienie różnicy jest kluczowe dla budowy niezawodnych integracji.

## Dwie metody autoryzacji

| Metoda | Przypadek użycia | Limit żądań | Wygasanie |
|--------|----------|------------|--------|
| **Mind Key** | Agenty LLM, narzędzia zautomatyzowane | Brak (nagłówek) / 60 min (zapytanie) | Nigdy |
| **JWT** | Interfejs dla człowieka, operacje na koncie | Brak | 7 dni |

## Mind Key (dla agentów)

Mind Key to token API o zakresie dzierżawcy. Uwierzytelnia dane pojedynczego
umysłu (wspomnienia, zadania, czat, skrypty itp.). Stosować do:

- Agentów LLM wywołujących API
- Skryptów automatyzacji w tle
- Konfiguracji serwera MCP
- Dowolnej długotrwałej integracji

### Autoryzacja nagłówkiem (zalecane)

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

### Parametr zapytania (dla narzędzi obsługujących tylko URL)

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

> [!WARNING]
> Parametr zapytania `?key=` jest ograniczony do **60 żądań na minutę**. Nagłówek
> Bearer nie ma limitu. Należy używać nagłówka zawsze, gdy klient obsługuje
> własne nagłówki.

### Tworzenie Mind Key

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

Odpowiedź zawiera `mind_key` — **należy go natychmiast zapisać**, jest
wyświetlany tylko raz.

### Wylistowanie umysłów

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

### Usuwanie umysłu (nieodwracalne!)

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

## JWT (dla ludzi)

JWT uwierzytelnia **konto użytkownika**, a nie konkretny umysł. Stosować do:

- Rejestracji konta i logowania
- Tworzenia / listowania / usuwania umysłów
- Współdzielenia umysłów z innymi użytkownikami
- Zarządzania subskrypcjami Web Push

### Rejestracja

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

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

### Logowanie

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

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

### Wygasanie JWT

JWT wygasają po **7 dniach**. Po wygaśnięciu należy po prostu ponownie wywołać
`/login`, aby uzyskać nowy. Mind Key nigdy nie wygasa, więc istniejące integracje
agentów nadal działają.

## Najlepsze praktyki bezpieczeństwa

> [!CRITICAL]
> - **Nigdy nie commitować Mind Key do gita.** Używać zmiennych środowiskowych.
> - **Nigdy nie logować Mind Key.** Maskować je w logach (`mk_***...***xyz`).
> - **Rotować klucze** w razie podejrzenia wycieku (usunąć umysł, utworzyć nowy).
> - **Używać jednego umysłu na projekt**, aby ograniczyć obszar rażenia przy wycieku klucza.

### Wzorzec zmiennych środowiskowych

```bash
# .env (NIGDY nie commitować tego pliku)
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}` },
});
```

### Konfiguracja serwera MCP

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

## Wzorzec wielu umysłów

Każdy użytkownik może mieć wiele umysłów. Typowe wzorce:

| Nazwa umysłu | Przeznaczenie |
|-----------|---------|
| `work` | Wspomnienia związane z pracą |
| `personal` | Preferencje osobiste, rodzina |
| `project-synapse` | Kontekst konkretnego projektu |
| `learning-german` | Postęp w nauce |
| `assistant-default` | Ogólnego przeznaczenia, zapasowy |

Należy używać różnych Mind Key dla różnych sesji LLM, aby utrzymać konteksty
oddzielone.

## Limity żądań

| Metoda autoryzacji | Limit | Zakres |
|-------------|-------|-------|
| Mind Key (nagłówek) | Brak | Na umysł |
| Mind Key (?key=) | 60/min | Na IP |
| JWT (nagłówek) | Brak | Na użytkownika |
| Endpointy publiczne | Brak | Globalny |

Nagłówki limitu żądań (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)
są dołączane do odpowiedzi, gdy ma to zastosowanie.

## Następne kroki

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — kiedy którego używać
- [Memory API](/docs/api/memory) — co można robić z Mind Key
- [User API](/docs/api/user) — zarządzanie kontem z JWT