# Authentication & Mind Keys
SUMMARY: Synapse の認証の仕組み：エージェント向け Mind Key、人間向け JWT、?key= はデフォルトで無効（Bearer のみ、AUTH_QUERY_KEY_MODE=deny）。

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx (?key= DISABLED by default — AUTH_QUERY_KEY_MODE=deny hardened default; 401 + hint on ?key=)
JWT: Authorization: Bearer eyJ... (120 req/min external IPs, unlimited internal; 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 エージェント、自動化ツール | 120/分（外部 Bearer）；?key= はデフォルトで無効（deny） | なし |
| JWT | ヒューマン向け UI、アカウント操作 | 120/分（外部IP） | 7 日 |
Mind Key（エージェント向け）
Mind Key はテナントスコープの API トークンです。単一 mind のデータ（メモリ、タスク、チャット、スクリプトなど）を認証します。以下に使用します。
- API を呼び出す LLM エージェント
- バックグラウンド自動化スクリプト
- MCP サーバー設定
- 任意の長期間の連携
ヘッダー認証（推奨）
[CODE BLOCK]
クエリパラメータ（デフォルトで無効）
[CODE BLOCK]
> [!WARNING]
>  クエリパラメータは、強化されたデフォルト  により無効です：サーバーは
>  に対して 401 とヒント "Query-param auth (?key=) is disabled" を返します。Bearer のみが安全なデフォルトです（SSOT：）。
> オペレーターが明示的に  を設定した場合のみ、 は 60 req/min（IP ごと）の
> 移行用バルブとして機能します。外部 Bearer クライアントは ID ごとに 120 req/min を取得し、信頼できる内部
> ネットワークは無制限です。
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（ヘッダー） | 120/分 外部 IP 基準（アイデンティティごと）；信頼できる内部ネットワークは無制限 | mind ごと |
| Mind Key（?key=、allow 時のみ） | 60/分 | IP ごと |
| JWT（ヘッダー） | 120/分 外部 IP 基準（アイデンティティごと）；信頼できる内部ネットワークは無制限 | ユーザーごと |
| パブリックエンドポイント | なし | グローバル |
該当する場合、レスポンスにレート制限ヘッダー（、、）が含まれます。
次のステップ
- Mind Key vs JWT — どちらを使うべきか
- Memory API — Mind Key でできること
- User API — JWT によるアカウント管理