# Authentication & Mind Keys

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

## 2 つの認証方法

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

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

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

- API を呼び出す LLM エージェント
- バックグラウンド自動化スクリプト
- MCP サーバー設定
- 任意の長期間の連携

### ヘッダー認証（推奨）

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

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

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

> [!WARNING]
> `?key=` クエリパラメータは **60 リクエスト/分** にレート制限されます。Bearer ヘッダーにはレート制限がありません。クライアントがカスタムヘッダーをサポートする場合は常にヘッダーを使用してください。

### Mind Key の作成

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

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

### mind の一覧

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

### mind の削除（不可逆！）

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

## JWT（人間向け）

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

- アカウントの登録とログイン
- mind の作成/一覧/削除
- 他のユーザーとの mind 共有
- Web Push サブスクリプション管理

### 登録

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

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

### ログイン

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

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

### JWT の有効期限

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

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

> [!CRITICAL]
> - **Mind Key を git にコミットしない。** 環境変数を使用してください。
> - **Mind Key をログに出力しない。** ログではマスクしてください（`mk_***...***xyz`）。
> - **漏洩が疑われる場合はキーをローテーション**（mind を削除し、新規作成）。
> - **プロジェクトごとに 1 つの mind を使用**し、キー漏洩時の被害範囲を限定。

### 環境変数パターン

```bash
# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone
```

```typescript
// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});
```

### MCP サーバー設定

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

## マルチ mind パターン

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

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

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

## レート制限

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

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

## 次のステップ

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — どちらを使うべきか
- [Memory API](/docs/api/memory) — Mind Key でできること
- [User API](/docs/api/user) — JWT によるアカウント管理