# Mind Key vs JWT — co i kiedy?

Synapse ma dwa tokeny autoryzacyjne. Wybór niewłaściwego prowadzi do błędów 401.
Ten przewodnik dostarcza jasnej ramy decyzyjnej.

## Szybka tabela decyzyjna

| Cel | Użyć |
|----------------|-----|
| Zapis / recall wspomnień | Mind Key |
| Wysyłanie / odpytywanie wiadomości czatu | Mind Key |
| Zarządzanie zadaniami | Mind Key |
| Zapis skryptów | Mind Key |
| Rejestracja webhooków | Mind Key |
| Sterowanie komputerami | Mind Key (po stronie użytkownika) / Computer Token (po stronie agenta) |
| Rejestracja konta użytkownika | Brak (publiczne) |
| Logowanie | Brak (publiczne) |
| Tworzenie / listowanie / usuwanie umysłów | JWT |
| Współdzielenie umysłu z innym użytkownikiem | JWT |
| Subskrypcja powiadomień Web Push | JWT |
| Przegląd dziennika audytu | Mind Key |

## Prosta reguła

> [!TIP]
> **Jeśli operacja dotyka danych pojedynczego umysłu → Mind Key.**
> **Jeśli zarządza kontem lub metadanymi umysłów → JWT.**

## Mind Key — token dostępu do danych

Mind Key daje dostęp do **danych jednego umysłu**. Jest długowiecznym tokenem,
który nigdy nie wygasa (dopóki umysł nie zostanie usunięty). Idealny do:

- Agentów LLM utrwalających wspomnienia między sesjami
- Zadań cron w tle
- Konfiguracji serwera MCP
- Integracji webhooków
- Aplikacji mobilnych odczytujących pamięć

### Co Mind Key może

- `GET /memory/recall` — odczyt wszystkich wspomnień w tym umyśle
- `POST /memory` — zapis/aktualizacja wspomnień
- `GET /chat/poll` — odczyt wiadomości czatu
- `POST /chat/reply` — wysyłanie wiadomości czatu
- `GET /mind/tasks` — lista zadań
- `POST /mind/task` — tworzenie zadań
- `POST /script` — zapis skryptów
- `POST /webhooks` — rejestracja webhooków
- `POST /computers/:id/commands` — kolejkowanie poleceń komputera

### Czego Mind Key NIE może

- Tworzyć / listować / usuwać umysłów (wymagany JWT)
- Współdzielić umysłu z innym użytkownikiem (wymagany JWT)
- Wyświetlać informacji o koncie użytkownika (wymagany JWT)
- Subskrybować Web Push (wymagany JWT)

## JWT — token zarządzania kontem

JWT uwierzytelnia **konto użytkownika**. Wygasa po 7 dniach i jest używany do
operacji na poziomie konta, które obejmują wiele umysłów lub innych użytkowników.

### Co JWT może

- `POST /minds` — utworzenie nowego umysłu (zwraca nowy Mind Key)
- `GET /minds` — lista wszystkich umysłów tego użytkownika
- `DELETE /minds/:id` — usunięcie umysłu
- `POST /sharing` — udostępnienie umysłu innemu użytkownikowi
- `POST /push/subscribe` — subskrypcja powiadomień Web Push
- `GET /sharing` — lista udostępnień umysłu

### Czego JWT NIE może

- Odczytywać / zapisywać wspomnień (wymagany Mind Key)
- Wysyłać wiadomości czatu (wymagany Mind Key)
- Zarządzać zadaniami (wymagany Mind Key)
- Rejestrować webhooków (wymagany Mind Key)

## Przypadek specjalny: Computer Token

Endpointy `/computers/me/*` (po stronie agenta, dla screen-remote-agent) używają
trzeciego typu tokena: **Computer Token**. Jest on zwracany przez
`POST /computers/register` przy realizacji kodu instalacyjnego i jest specyficzny
dla jednego zarejestrowanego komputera.

| Endpoint | Autoryzacja |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key lub JWT |
| `POST /computers/:id/commands` | Mind Key lub JWT |

## Typowe wzorce

### Wzorzec 1: pojedynczy agent LLM

1. Jedna rejestracja → uzyskanie JWT
2. Utworzenie jednego umysłu → uzyskanie Mind Key
3. LLM używa Mind Key do wszystkiego

### Wzorzec 2: agent wieloprojektowy

1. Jedna rejestracja → uzyskanie JWT
2. Utworzenie wielu umysłów (work, personal, project-x) → uzyskanie wielu Mind Key
3. LLM ładuje różne Mind Key w zależności od kontekstu

### Wzorzec 3: współdzielenie zespołu

1. Użytkownik A tworzy umysł → uzyskuje Mind Key A
2. Użytkownik A udostępnia użytkownikowi B przez JWT (`POST /sharing`)
3. Użytkownik B ma teraz dostęp przez własny JWT
4. Do dostępu przez LLM użytkownik B musi utworzyć własny Mind Key (lub użyć A)

### Wzorzec 4: serwer MCP

Serwery MCP zawsze używają Mind Key (ustawionego przez zmienną środowiskową
`SYNAPSE_MIND_KEY`). Jedna instancja serwera MCP = jeden umysł. Dla dostępu do
wielu umysłów należy uruchomić wiele instancji MCP lub zaimplementować
przełączanie umysłów po stronie klienta.

## Ściąga formatów tokenów

| Token | Format | Przykład |
|-------|--------|---------|
| Mind Key | `mk_` + 36 znaków | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 znaków | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Następne kroki

- [Autoryzacja](/docs/getting-started/authentication) — pełny przewodnik autoryzacji
- [User & Minds API](/docs/api/user) — endpointy chronione JWT
- [Memory API](/docs/api/memory) — endpointy chronione Mind Key