{"title":"Mind Key vs JWT — co i kiedy?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Przewodnik decyzyjny: Mind Key do dostępu do danych agenta, JWT do zarządzania kontem.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":665,"read_minutes":3,"llm_context":"Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.\nJWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.\nSimple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.\nException: /computers/me/* uses Computer Token (not Mind Key or JWT).\n","lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# Mind Key vs JWT — co i kiedy?\n\nSynapse ma dwa tokeny autoryzacyjne. Wybór niewłaściwego prowadzi do błędów 401.\nTen przewodnik dostarcza jasnej ramy decyzyjnej.\n\n## Szybka tabela decyzyjna\n\n| Cel | Użyć |\n|----------------|-----|\n| Zapis / recall wspomnień | Mind Key |\n| Wysyłanie / odpytywanie wiadomości czatu | Mind Key |\n| Zarządzanie zadaniami | Mind Key |\n| Zapis skryptów | Mind Key |\n| Rejestracja webhooków | Mind Key |\n| Sterowanie komputerami | Mind Key (po stronie użytkownika) / Computer Token (po stronie agenta) |\n| Rejestracja konta użytkownika | Brak (publiczne) |\n| Logowanie | Brak (publiczne) |\n| Tworzenie / listowanie / usuwanie umysłów | JWT |\n| Współdzielenie umysłu z innym użytkownikiem | JWT |\n| Subskrypcja powiadomień Web Push | JWT |\n| Przegląd dziennika audytu | Mind Key |\n\n## Prosta reguła\n\n> [!TIP]\n> **Jeśli operacja dotyka danych pojedynczego umysłu → Mind Key.**\n> **Jeśli zarządza kontem lub metadanymi umysłów → JWT.**\n\n## Mind Key — token dostępu do danych\n\nMind Key daje dostęp do **danych jednego umysłu**. Jest długowiecznym tokenem,\nktóry nigdy nie wygasa (dopóki umysł nie zostanie usunięty). Idealny do:\n\n- Agentów LLM utrwalających wspomnienia między sesjami\n- Zadań cron w tle\n- Konfiguracji serwera MCP\n- Integracji webhooków\n- Aplikacji mobilnych odczytujących pamięć\n\n### Co Mind Key może\n\n- `GET /memory/recall` — odczyt wszystkich wspomnień w tym umyśle\n- `POST /memory` — zapis/aktualizacja wspomnień\n- `GET /chat/poll` — odczyt wiadomości czatu\n- `POST /chat/reply` — wysyłanie wiadomości czatu\n- `GET /mind/tasks` — lista zadań\n- `POST /mind/task` — tworzenie zadań\n- `POST /script` — zapis skryptów\n- `POST /webhooks` — rejestracja webhooków\n- `POST /computers/:id/commands` — kolejkowanie poleceń komputera\n\n### Czego Mind Key NIE może\n\n- Tworzyć / listować / usuwać umysłów (wymagany JWT)\n- Współdzielić umysłu z innym użytkownikiem (wymagany JWT)\n- Wyświetlać informacji o koncie użytkownika (wymagany JWT)\n- Subskrybować Web Push (wymagany JWT)\n\n## JWT — token zarządzania kontem\n\nJWT uwierzytelnia **konto użytkownika**. Wygasa po 7 dniach i jest używany do\noperacji na poziomie konta, które obejmują wiele umysłów lub innych użytkowników.\n\n### Co JWT może\n\n- `POST /minds` — utworzenie nowego umysłu (zwraca nowy Mind Key)\n- `GET /minds` — lista wszystkich umysłów tego użytkownika\n- `DELETE /minds/:id` — usunięcie umysłu\n- `POST /sharing` — udostępnienie umysłu innemu użytkownikowi\n- `POST /push/subscribe` — subskrypcja powiadomień Web Push\n- `GET /sharing` — lista udostępnień umysłu\n\n### Czego JWT NIE może\n\n- Odczytywać / zapisywać wspomnień (wymagany Mind Key)\n- Wysyłać wiadomości czatu (wymagany Mind Key)\n- Zarządzać zadaniami (wymagany Mind Key)\n- Rejestrować webhooków (wymagany Mind Key)\n\n## Przypadek specjalny: Computer Token\n\nEndpointy `/computers/me/*` (po stronie agenta, dla screen-remote-agent) używają\ntrzeciego typu tokena: **Computer Token**. Jest on zwracany przez\n`POST /computers/register` przy realizacji kodu instalacyjnego i jest specyficzny\ndla jednego zarejestrowanego komputera.\n\n| Endpoint | Autoryzacja |\n|----------|------|\n| `GET /computers/me/poll` | Computer Token |\n| `POST /computers/me/commands/:cid/result` | Computer Token |\n| `GET /computers/list` | Mind Key lub JWT |\n| `POST /computers/:id/commands` | Mind Key lub JWT |\n\n## Typowe wzorce\n\n### Wzorzec 1: pojedynczy agent LLM\n\n1. Jedna rejestracja → uzyskanie JWT\n2. Utworzenie jednego umysłu → uzyskanie Mind Key\n3. LLM używa Mind Key do wszystkiego\n\n### Wzorzec 2: agent wieloprojektowy\n\n1. Jedna rejestracja → uzyskanie JWT\n2. Utworzenie wielu umysłów (work, personal, project-x) → uzyskanie wielu Mind Key\n3. LLM ładuje różne Mind Key w zależności od kontekstu\n\n### Wzorzec 3: współdzielenie zespołu\n\n1. Użytkownik A tworzy umysł → uzyskuje Mind Key A\n2. Użytkownik A udostępnia użytkownikowi B przez JWT (`POST /sharing`)\n3. Użytkownik B ma teraz dostęp przez własny JWT\n4. Do dostępu przez LLM użytkownik B musi utworzyć własny Mind Key (lub użyć A)\n\n### Wzorzec 4: serwer MCP\n\nSerwery MCP zawsze używają Mind Key (ustawionego przez zmienną środowiskową\n`SYNAPSE_MIND_KEY`). Jedna instancja serwera MCP = jeden umysł. Dla dostępu do\nwielu umysłów należy uruchomić wiele instancji MCP lub zaimplementować\nprzełączanie umysłów po stronie klienta.\n\n## Ściąga formatów tokenów\n\n| Token | Format | Przykład |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36 znaków | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 znaków | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Następne kroki\n\n- [Autoryzacja](/docs/getting-started/authentication) — pełny przewodnik autoryzacji\n- [User & Minds API](/docs/api/user) — endpointy chronione JWT\n- [Memory API](/docs/api/memory) — endpointy chronione Mind Key\n","content_html":"<h1>Mind Key vs JWT — co i kiedy?</h1>\n<p>Synapse ma dwa tokeny autoryzacyjne. Wybór niewłaściwego prowadzi do błędów 401.\nTen przewodnik dostarcza jasnej ramy decyzyjnej.</p>\n<h2>Szybka tabela decyzyjna</h2>\n<table>\n<thead>\n<tr>\n<th>Cel</th>\n<th>Użyć</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Zapis / recall wspomnień</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Wysyłanie / odpytywanie wiadomości czatu</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Zarządzanie zadaniami</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Zapis skryptów</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Rejestracja webhooków</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Sterowanie komputerami</td>\n<td>Mind Key (po stronie użytkownika) / Computer Token (po stronie agenta)</td>\n</tr>\n<tr>\n<td>Rejestracja konta użytkownika</td>\n<td>Brak (publiczne)</td>\n</tr>\n<tr>\n<td>Logowanie</td>\n<td>Brak (publiczne)</td>\n</tr>\n<tr>\n<td>Tworzenie / listowanie / usuwanie umysłów</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Współdzielenie umysłu z innym użytkownikiem</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Subskrypcja powiadomień Web Push</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Przegląd dziennika audytu</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>Prosta reguła</h2>\n<div class=\"callout callout-ok\">**Jeśli operacja dotyka danych pojedynczego umysłu → Mind Key.**\n**Jeśli zarządza kontem lub metadanymi umysłów → JWT.**</div><h2>Mind Key — token dostępu do danych</h2>\n<p>Mind Key daje dostęp do <strong>danych jednego umysłu</strong>. Jest długowiecznym tokenem,\nktóry nigdy nie wygasa (dopóki umysł nie zostanie usunięty). Idealny do:</p>\n<ul>\n<li>Agentów LLM utrwalających wspomnienia między sesjami</li>\n<li>Zadań cron w tle</li>\n<li>Konfiguracji serwera MCP</li>\n<li>Integracji webhooków</li>\n<li>Aplikacji mobilnych odczytujących pamięć</li>\n</ul>\n<h3>Co Mind Key może</h3>\n<ul>\n<li><code>GET /memory/recall</code> — odczyt wszystkich wspomnień w tym umyśle</li>\n<li><code>POST /memory</code> — zapis/aktualizacja wspomnień</li>\n<li><code>GET /chat/poll</code> — odczyt wiadomości czatu</li>\n<li><code>POST /chat/reply</code> — wysyłanie wiadomości czatu</li>\n<li><code>GET /mind/tasks</code> — lista zadań</li>\n<li><code>POST /mind/task</code> — tworzenie zadań</li>\n<li><code>POST /script</code> — zapis skryptów</li>\n<li><code>POST /webhooks</code> — rejestracja webhooków</li>\n<li><code>POST /computers/:id/commands</code> — kolejkowanie poleceń komputera</li>\n</ul>\n<h3>Czego Mind Key NIE może</h3>\n<ul>\n<li>Tworzyć / listować / usuwać umysłów (wymagany JWT)</li>\n<li>Współdzielić umysłu z innym użytkownikiem (wymagany JWT)</li>\n<li>Wyświetlać informacji o koncie użytkownika (wymagany JWT)</li>\n<li>Subskrybować Web Push (wymagany JWT)</li>\n</ul>\n<h2>JWT — token zarządzania kontem</h2>\n<p>JWT uwierzytelnia <strong>konto użytkownika</strong>. Wygasa po 7 dniach i jest używany do\noperacji na poziomie konta, które obejmują wiele umysłów lub innych użytkowników.</p>\n<h3>Co JWT może</h3>\n<ul>\n<li><code>POST /minds</code> — utworzenie nowego umysłu (zwraca nowy Mind Key)</li>\n<li><code>GET /minds</code> — lista wszystkich umysłów tego użytkownika</li>\n<li><code>DELETE /minds/:id</code> — usunięcie umysłu</li>\n<li><code>POST /sharing</code> — udostępnienie umysłu innemu użytkownikowi</li>\n<li><code>POST /push/subscribe</code> — subskrypcja powiadomień Web Push</li>\n<li><code>GET /sharing</code> — lista udostępnień umysłu</li>\n</ul>\n<h3>Czego JWT NIE może</h3>\n<ul>\n<li>Odczytywać / zapisywać wspomnień (wymagany Mind Key)</li>\n<li>Wysyłać wiadomości czatu (wymagany Mind Key)</li>\n<li>Zarządzać zadaniami (wymagany Mind Key)</li>\n<li>Rejestrować webhooków (wymagany Mind Key)</li>\n</ul>\n<h2>Przypadek specjalny: Computer Token</h2>\n<p>Endpointy <code>/computers/me/*</code> (po stronie agenta, dla screen-remote-agent) używają\ntrzeciego typu tokena: <strong>Computer Token</strong>. Jest on zwracany przez\n<code>POST /computers/register</code> przy realizacji kodu instalacyjnego i jest specyficzny\ndla jednego zarejestrowanego komputera.</p>\n<table>\n<thead>\n<tr>\n<th>Endpoint</th>\n<th>Autoryzacja</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /computers/me/poll</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>POST /computers/me/commands/:cid/result</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>GET /computers/list</code></td>\n<td>Mind Key lub JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key lub JWT</td>\n</tr>\n</tbody></table>\n<h2>Typowe wzorce</h2>\n<h3>Wzorzec 1: pojedynczy agent LLM</h3>\n<ol>\n<li>Jedna rejestracja → uzyskanie JWT</li>\n<li>Utworzenie jednego umysłu → uzyskanie Mind Key</li>\n<li>LLM używa Mind Key do wszystkiego</li>\n</ol>\n<h3>Wzorzec 2: agent wieloprojektowy</h3>\n<ol>\n<li>Jedna rejestracja → uzyskanie JWT</li>\n<li>Utworzenie wielu umysłów (work, personal, project-x) → uzyskanie wielu Mind Key</li>\n<li>LLM ładuje różne Mind Key w zależności od kontekstu</li>\n</ol>\n<h3>Wzorzec 3: współdzielenie zespołu</h3>\n<ol>\n<li>Użytkownik A tworzy umysł → uzyskuje Mind Key A</li>\n<li>Użytkownik A udostępnia użytkownikowi B przez JWT (<code>POST /sharing</code>)</li>\n<li>Użytkownik B ma teraz dostęp przez własny JWT</li>\n<li>Do dostępu przez LLM użytkownik B musi utworzyć własny Mind Key (lub użyć A)</li>\n</ol>\n<h3>Wzorzec 4: serwer MCP</h3>\n<p>Serwery MCP zawsze używają Mind Key (ustawionego przez zmienną środowiskową\n<code>SYNAPSE_MIND_KEY</code>). Jedna instancja serwera MCP = jeden umysł. Dla dostępu do\nwielu umysłów należy uruchomić wiele instancji MCP lub zaimplementować\nprzełączanie umysłów po stronie klienta.</p>\n<h2>Ściąga formatów tokenów</h2>\n<table>\n<thead>\n<tr>\n<th>Token</th>\n<th>Format</th>\n<th>Przykład</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key</td>\n<td><code>mk_</code> + 36 znaków</td>\n<td><code>mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789</code></td>\n</tr>\n<tr>\n<td>JWT</td>\n<td><code>eyJ</code> + base64</td>\n<td><code>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</code></td>\n</tr>\n<tr>\n<td>Computer Token</td>\n<td><code>ct_</code> + 36 znaków</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Następne kroki</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Autoryzacja</a> — pełny przewodnik autoryzacji</li>\n<li><a href=\"/docs/api/user\">User &amp; Minds API</a> — endpointy chronione JWT</li>\n<li><a href=\"/docs/api/memory\">Memory API</a> — endpointy chronione Mind Key</li>\n</ul>\n","urls":{"html":"/docs/getting-started/mind-key-vs-jwt","text":"/docs/getting-started/mind-key-vs-jwt?format=text","json":"/docs/getting-started/mind-key-vs-jwt?format=json","llm":"/docs/getting-started/mind-key-vs-jwt?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}