{"title":"Autoryzacja i Mind Key","slug":"authentication","category":"getting-started","summary":"Jak działa autoryzacja w Synapse: Mind Key dla agentów, JWT dla ludzi, ?key= dla narzędzi obsługujących tylko URL.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":471,"read_minutes":2,"llm_context":"Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).\nMind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)\nJWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)\nMind Key is shown only once at creation. Store it permanently.\nEach mind has exactly one Mind Key. Multiple minds = multiple keys.\n","lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# Autoryzacja i Mind Key\n\nSynapse używa dwóch metod autoryzacji, każda zoptymalizowana pod inny przypadek.\nZrozumienie różnicy jest kluczowe dla budowy niezawodnych integracji.\n\n## Dwie metody autoryzacji\n\n| Metoda | Przypadek użycia | Limit żądań | Wygasanie |\n|--------|----------|------------|--------|\n| **Mind Key** | Agenty LLM, narzędzia zautomatyzowane | Brak (nagłówek) / 60 min (zapytanie) | Nigdy |\n| **JWT** | Interfejs dla człowieka, operacje na koncie | Brak | 7 dni |\n\n## Mind Key (dla agentów)\n\nMind Key to token API o zakresie dzierżawcy. Uwierzytelnia dane pojedynczego\numysłu (wspomnienia, zadania, czat, skrypty itp.). Stosować do:\n\n- Agentów LLM wywołujących API\n- Skryptów automatyzacji w tle\n- Konfiguracji serwera MCP\n- Dowolnej długotrwałej integracji\n\n### Autoryzacja nagłówkiem (zalecane)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Parametr zapytania (dla narzędzi obsługujących tylko URL)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Parametr zapytania `?key=` jest ograniczony do **60 żądań na minutę**. Nagłówek\n> Bearer nie ma limitu. Należy używać nagłówka zawsze, gdy klient obsługuje\n> własne nagłówki.\n\n### Tworzenie Mind Key\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/minds \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Work Mind\", \"description\": \"Project memories\"}'\n```\n\nOdpowiedź zawiera `mind_key` — **należy go natychmiast zapisać**, jest\nwyświetlany tylko raz.\n\n### Wylistowanie umysłów\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Usuwanie umysłu (nieodwracalne!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (dla ludzi)\n\nJWT uwierzytelnia **konto użytkownika**, a nie konkretny umysł. Stosować do:\n\n- Rejestracji konta i logowania\n- Tworzenia / listowania / usuwania umysłów\n- Współdzielenia umysłów z innymi użytkownikami\n- Zarządzania subskrypcjami Web Push\n\n### Rejestracja\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nZwraca: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Logowanie\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nZwraca: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Wygasanie JWT\n\nJWT wygasają po **7 dniach**. Po wygaśnięciu należy po prostu ponownie wywołać\n`/login`, aby uzyskać nowy. Mind Key nigdy nie wygasa, więc istniejące integracje\nagentów nadal działają.\n\n## Najlepsze praktyki bezpieczeństwa\n\n> [!CRITICAL]\n> - **Nigdy nie commitować Mind Key do gita.** Używać zmiennych środowiskowych.\n> - **Nigdy nie logować Mind Key.** Maskować je w logach (`mk_***...***xyz`).\n> - **Rotować klucze** w razie podejrzenia wycieku (usunąć umysł, utworzyć nowy).\n> - **Używać jednego umysłu na projekt**, aby ograniczyć obszar rażenia przy wycieku klucza.\n\n### Wzorzec zmiennych środowiskowych\n\n```bash\n# .env (NIGDY nie commitować tego pliku)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone\n```\n\n```typescript\n// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n headers: { Authorization: `Bearer ${mindKey}` },\n});\n```\n\n### Konfiguracja serwera MCP\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_yourMindKeyHere\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n## Wzorzec wielu umysłów\n\nKażdy użytkownik może mieć wiele umysłów. Typowe wzorce:\n\n| Nazwa umysłu | Przeznaczenie |\n|-----------|---------|\n| `work` | Wspomnienia związane z pracą |\n| `personal` | Preferencje osobiste, rodzina |\n| `project-synapse` | Kontekst konkretnego projektu |\n| `learning-german` | Postęp w nauce |\n| `assistant-default` | Ogólnego przeznaczenia, zapasowy |\n\nNależy używać różnych Mind Key dla różnych sesji LLM, aby utrzymać konteksty\noddzielone.\n\n## Limity żądań\n\n| Metoda autoryzacji | Limit | Zakres |\n|-------------|-------|-------|\n| Mind Key (nagłówek) | Brak | Na umysł |\n| Mind Key (?key=) | 60/min | Na IP |\n| JWT (nagłówek) | Brak | Na użytkownika |\n| Endpointy publiczne | Brak | Globalny |\n\nNagłówki limitu żądań (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)\nsą dołączane do odpowiedzi, gdy ma to zastosowanie.\n\n## Następne kroki\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — kiedy którego używać\n- [Memory API](/docs/api/memory) — co można robić z Mind Key\n- [User API](/docs/api/user) — zarządzanie kontem z JWT\n","content_html":"

Autoryzacja i Mind Key

\n

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

\n

Dwie metody autoryzacji

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MetodaPrzypadek użyciaLimit żądańWygasanie
Mind KeyAgenty LLM, narzędzia zautomatyzowaneBrak (nagłówek) / 60 min (zapytanie)Nigdy
JWTInterfejs dla człowieka, operacje na koncieBrak7 dni
\n

Mind Key (dla agentów)

\n

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

\n\n

Autoryzacja nagłówkiem (zalecane)

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

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

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
Parametr zapytania `?key=` jest ograniczony do **60 żądań na minutę**. Nagłówek\nBearer nie ma limitu. Należy używać nagłówka zawsze, gdy klient obsługuje\nwłasne nagłówki.

Tworzenie Mind Key

\n
curl -X POST https://synapse.schaefer.zone/minds \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"name": "Work Mind", "description": "Project memories"}'

Odpowiedź zawiera mind_key — należy go natychmiast zapisać, jest\nwyświetlany tylko raz.

\n

Wylistowanie umysłów

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

Usuwanie umysłu (nieodwracalne!)

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

JWT (dla ludzi)

\n

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

\n\n

Rejestracja

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

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

\n

Logowanie

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

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

\n

Wygasanie JWT

\n

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

\n

Najlepsze praktyki bezpieczeństwa

\n

Wzorzec zmiennych środowiskowych

\n
# .env (NIGDY nie commitować tego pliku)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone
// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n  headers: { Authorization: `Bearer ${mindKey}` },\n});

Konfiguracja serwera MCP

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

Wzorzec wielu umysłów

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Nazwa umysłuPrzeznaczenie
workWspomnienia związane z pracą
personalPreferencje osobiste, rodzina
project-synapseKontekst konkretnego projektu
learning-germanPostęp w nauce
assistant-defaultOgólnego przeznaczenia, zapasowy
\n

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

\n

Limity żądań

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Metoda autoryzacjiLimitZakres
Mind Key (nagłówek)BrakNa umysł
Mind Key (?key=)60/minNa IP
JWT (nagłówek)BrakNa użytkownika
Endpointy publiczneBrakGlobalny
\n

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

\n

Następne kroki

\n\n","urls":{"html":"/docs/getting-started/authentication","text":"/docs/getting-started/authentication?format=text","json":"/docs/getting-started/authentication?format=json","llm":"/docs/getting-started/authentication?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}