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

Prosta reguła

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.

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

Następne kroki

• Autoryzacja — pełny przewodnik autoryzacji
• User & Minds API — endpointy chronione JWT
• Memory API — endpointy chronione Mind Key