{"title":"Authentication & Mind Keys","slug":"authentication","category":"getting-started","summary":"Synapse の認証の仕組み：エージェント向け Mind Key、人間向け JWT、URL 単体ツール向け ?key=。","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":272,"read_minutes":1,"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":"ja","translated":true,"requested_lang":"ja","content_markdown":"\n# Authentication & Mind Keys\n\nSynapse は 2 つの認証方法を使用し、それぞれが異なるユースケースに最適化されています。信頼できる連携を構築するには、この違いを理解することが不可欠です。\n\n## 2 つの認証方法\n\n| 方法 | ユースケース | レート制限 | 有効期限 |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM エージェント、自動化ツール | なし（ヘッダー）/ 60/分（クエリ） | なし |\n| **JWT** | ヒューマン向け UI、アカウント操作 | なし | 7 日 |\n\n## Mind Key（エージェント向け）\n\nMind Key はテナントスコープの API トークンです。単一 mind のデータ（メモリ、タスク、チャット、スクリプトなど）を認証します。以下に使用します。\n\n- API を呼び出す LLM エージェント\n- バックグラウンド自動化スクリプト\n- MCP サーバー設定\n- 任意の長期間の連携\n\n### ヘッダー認証（推奨）\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### クエリパラメータ（URL 単体ツール向け）\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> `?key=` クエリパラメータは **60 リクエスト/分** にレート制限されます。Bearer ヘッダーにはレート制限がありません。クライアントがカスタムヘッダーをサポートする場合は常にヘッダーを使用してください。\n\n### 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\nレスポンスに `mind_key` が含まれます — **すぐに保存してください**。一度しか表示されません。\n\n### mind の一覧\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### mind の削除（不可逆！）\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT（人間向け）\n\nJWT は特定の mind ではなく**ユーザーアカウント**を認証します。以下に使用します。\n\n- アカウントの登録とログイン\n- mind の作成/一覧/削除\n- 他のユーザーとの mind 共有\n- Web Push サブスクリプション管理\n\n### 登録\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\n返却値：`{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### ログイン\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\n返却値：`{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### JWT の有効期限\n\nJWT は **7 日後**に期限切れになります。期限切れの場合は、再度 `/login` を呼び出して新しい JWT を取得してください。Mind Key は期限切れにならないため、既存のエージェント連携は継続して動作します。\n\n## セキュリティのベストプラクティス\n\n> [!CRITICAL]\n> - **Mind Key を git にコミットしない。** 環境変数を使用してください。\n> - **Mind Key をログに出力しない。** ログではマスクしてください（`mk_***...***xyz`）。\n> - **漏洩が疑われる場合はキーをローテーション**（mind を削除し、新規作成）。\n> - **プロジェクトごとに 1 つの mind を使用**し、キー漏洩時の被害範囲を限定。\n\n### 環境変数パターン\n\n```bash\n# .env (NEVER commit this file)\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### 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## マルチ mind パターン\n\n各ユーザーは複数の mind を持てます。よくあるパターン：\n\n| Mind 名 | 目的 |\n|-----------|---------|\n| `work` | 仕事関連のメモリ |\n| `personal` | 個人の設定、家族 |\n| `project-synapse` | 特定プロジェクトのコンテキスト |\n| `learning-german` | 学習の進捗 |\n| `assistant-default` | 汎用フォールバック |\n\n異なる LLM セッションで異なる Mind Key を使用し、コンテキストを分離してください。\n\n## レート制限\n\n| 認証方法 | 制限 | スコープ |\n|-------------|-------|-------|\n| Mind Key（ヘッダー） | なし | mind ごと |\n| Mind Key（?key=） | 60/分 | IP ごと |\n| JWT（ヘッダー） | なし | ユーザーごと |\n| パブリックエンドポイント | なし | グローバル |\n\n該当する場合、レスポンスにレート制限ヘッダー（`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`Retry-After`）が含まれます。\n\n## 次のステップ\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — どちらを使うべきか\n- [Memory API](/docs/api/memory) — Mind Key でできること\n- [User API](/docs/api/user) — JWT によるアカウント管理\n","content_html":"

Authentication & Mind Keys

\n

Synapse は 2 つの認証方法を使用し、それぞれが異なるユースケースに最適化されています。信頼できる連携を構築するには、この違いを理解することが不可欠です。

\n

2 つの認証方法

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方法ユースケースレート制限有効期限
Mind KeyLLM エージェント、自動化ツールなし（ヘッダー）/ 60/分（クエリ）なし
JWTヒューマン向け UI、アカウント操作なし7 日
\n

Mind Key（エージェント向け）

\n

Mind Key はテナントスコープの API トークンです。単一 mind のデータ（メモリ、タスク、チャット、スクリプトなど）を認証します。以下に使用します。

\n\n

ヘッダー認証（推奨）

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

クエリパラメータ（URL 単体ツール向け）

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
`?key=` クエリパラメータは **60 リクエスト/分** にレート制限されます。Bearer ヘッダーにはレート制限がありません。クライアントがカスタムヘッダーをサポートする場合は常にヘッダーを使用してください。

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"}'

レスポンスに mind_key が含まれます — すぐに保存してください。一度しか表示されません。

\n

mind の一覧

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

mind の削除（不可逆！）

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

JWT（人間向け）

\n

JWT は特定の mind ではなくユーザーアカウントを認証します。以下に使用します。

\n\n

登録

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

返却値：{ "jwt": "eyJ...", "user": {...} }

\n

ログイン

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

返却値：{ "jwt": "eyJ...", "user": {...} }

\n

JWT の有効期限

\n

JWT は 7 日後に期限切れになります。期限切れの場合は、再度 /login を呼び出して新しい JWT を取得してください。Mind Key は期限切れにならないため、既存のエージェント連携は継続して動作します。

\n

セキュリティのベストプラクティス

\n

環境変数パターン

\n
# .env (NEVER commit this file)\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});

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}

マルチ mind パターン

\n

各ユーザーは複数の mind を持てます。よくあるパターン：

\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
Mind 名目的
work仕事関連のメモリ
personal個人の設定、家族
project-synapse特定プロジェクトのコンテキスト
learning-german学習の進捗
assistant-default汎用フォールバック
\n

異なる LLM セッションで異なる Mind Key を使用し、コンテキストを分離してください。

\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\n
認証方法制限スコープ
Mind Key（ヘッダー）なしmind ごと
Mind Key（?key=）60/分IP ごと
JWT（ヘッダー）なしユーザーごと
パブリックエンドポイントなしグローバル
\n

該当する場合、レスポンスにレート制限ヘッダー（X-RateLimit-Limit、X-RateLimit-Remaining、Retry-After）が含まれます。

\n

次のステップ

\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"]}