# Authentication & Mind Keys
SUMMARY: Synapse の認証の仕組み：エージェント向け Mind Key、人間向け JWT、URL 単体ツール向け ?key=。

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

Authentication & Mind Keys
Synapse は 2 つの認証方法を使用し、それぞれが異なるユースケースに最適化されています。信頼できる連携を構築するには、この違いを理解することが不可欠です。
2 つの認証方法
| 方法 | ユースケース | レート制限 | 有効期限 |
|--------|----------|------------|--------|
| Mind Key | LLM エージェント、自動化ツール | なし（ヘッダー）/ 60/分（クエリ） | なし |
| JWT | ヒューマン向け UI、アカウント操作 | なし | 7 日 |
Mind Key（エージェント向け）
Mind Key はテナントスコープの API トークンです。単一 mind のデータ（メモリ、タスク、チャット、スクリプトなど）を認証します。以下に使用します。
- API を呼び出す LLM エージェント
- バックグラウンド自動化スクリプト
- MCP サーバー設定
- 任意の長期間の連携
ヘッダー認証（推奨）
[CODE BLOCK]
クエリパラメータ（URL 単体ツール向け）
[CODE BLOCK]
> [!WARNING]
>  クエリパラメータは 60 リクエスト/分 にレート制限されます。Bearer ヘッダーにはレート制限がありません。クライアントがカスタムヘッダーをサポートする場合は常にヘッダーを使用してください。
Mind Key の作成
[CODE BLOCK]
レスポンスに  が含まれます — すぐに保存してください。一度しか表示されません。
mind の一覧
[CODE BLOCK]
mind の削除（不可逆！）
[CODE BLOCK]
JWT（人間向け）
JWT は特定の mind ではなくユーザーアカウントを認証します。以下に使用します。
- アカウントの登録とログイン
- mind の作成/一覧/削除
- 他のユーザーとの mind 共有
- Web Push サブスクリプション管理
登録
[CODE BLOCK]
返却値：
ログイン
[CODE BLOCK]
返却値：
JWT の有効期限
JWT は 7 日後に期限切れになります。期限切れの場合は、再度  を呼び出して新しい JWT を取得してください。Mind Key は期限切れにならないため、既存のエージェント連携は継続して動作します。
セキュリティのベストプラクティス
> [!CRITICAL]
> - Mind Key を git にコミットしない。 環境変数を使用してください。
> - Mind Key をログに出力しない。 ログではマスクしてください（）。
> - 漏洩が疑われる場合はキーをローテーション（mind を削除し、新規作成）。
> - プロジェクトごとに 1 つの mind を使用し、キー漏洩時の被害範囲を限定。
環境変数パターン
[CODE BLOCK]
[CODE BLOCK]
MCP サーバー設定
[CODE BLOCK]
マルチ mind パターン
各ユーザーは複数の mind を持てます。よくあるパターン：
| Mind 名 | 目的 |
|-----------|---------|
|  | 仕事関連のメモリ |
|  | 個人の設定、家族 |
|  | 特定プロジェクトのコンテキスト |
|  | 学習の進捗 |
|  | 汎用フォールバック |
異なる LLM セッションで異なる Mind Key を使用し、コンテキストを分離してください。
レート制限
| 認証方法 | 制限 | スコープ |
|-------------|-------|-------|
| Mind Key（ヘッダー） | なし | mind ごと |
| Mind Key（?key=） | 60/分 | IP ごと |
| JWT（ヘッダー） | なし | ユーザーごと |
| パブリックエンドポイント | なし | グローバル |
該当する場合、レスポンスにレート制限ヘッダー（、、）が含まれます。
次のステップ
- Mind Key vs JWT — どちらを使うべきか
- Memory API — Mind Key でできること
- User API — JWT によるアカウント管理