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

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)

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

Parametr zapytania (domyślnie wyłączone)

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

Tworzenie Mind Key

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

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

Usuwanie umysłu (nieodwracalne!)

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

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

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

Wzorzec zmiennych środowiskowych

# .env (NIGDY nie commitować tego pliku)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone

// 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

{
  "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:

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

Limity żądań

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 — kiedy którego używać
• Memory API — co można robić z Mind Key
• User API — zarządzanie kontem z JWT