# Mind Key vs JWT — どちらを使うべきか

Synapse には 2 つの認証トークンがあります。誤った方を選ぶと 401 エラーになります。本ガイドは明確な判断基準を提供します。

## クイック判断表

| やりたいこと | 使用するもの |
|----------------|-----|
| メモリの保存/再取得 | Mind Key |
| チャットメッセージの送信/ポーリング | Mind Key |
| タスク管理 | Mind Key |
| スクリプトの保存 | Mind Key |
| Webhook の登録 | Mind Key |
| コンピュータの制御 | Mind Key（ユーザー側）/ Computer Token（エージェント側） |
| ユーザーアカウントの登録 | なし（パブリック） |
| ログイン | なし（パブリック） |
| mind の作成/一覧/削除 | JWT |
| 他のユーザーとの mind 共有 | JWT |
| Web Push 通知の購読 | JWT |
| 監査ログの閲覧 | Mind Key |

## シンプルなルール

> [!TIP]
> **単一 mind のデータに触れる場合 → Mind Key。**
> **アカウントや mind メタデータを管理する場合 → JWT。**

## Mind Key — データアクセス権

Mind Key は**1 つの mind のデータ**へのアクセスを許可します。期限切れにならない長期間のトークンです（mind が削除されるまで）。以下に最適です。

- セッションをまたいでメモリを永続化する LLM エージェント
- バックグラウンド cron ジョブ
- MCP サーバー設定
- Webhook 連携
- メモリを読むモバイルアプリ

### Mind Key でできること

- `GET /memory/recall` — この mind の全メモリを読む
- `POST /memory` — メモリの保存/更新
- `GET /chat/poll` — チャットメッセージの読み取り
- `POST /chat/reply` — チャットメッセージの送信
- `GET /mind/tasks` — タスクの一覧
- `POST /mind/task` — タスクの作成
- `POST /script` — スクリプトの保存
- `POST /webhooks` — Webhook の登録
- `POST /computers/:id/commands` — コンピュータコマンドのキューイング

### Mind Key でできないこと

- mind の作成/一覧/削除（JWT が必要）
- 他のユーザーとの mind 共有（JWT が必要）
- ユーザーアカウント情報の閲覧（JWT が必要）
- Web Push の購読（JWT が必要）

## JWT — アカウント管理トークン

JWT は**ユーザーアカウント**を認証します。7 日後に期限切れとなり、複数の mind にまたがる、または他のユーザーを含むアカウントレベルの操作に使用されます。

### JWT でできること

- `POST /minds` — 新しい mind の作成（新しい Mind Key を返す）
- `GET /minds` — このユーザーの全 mind の一覧
- `DELETE /minds/:id` — mind の削除
- `POST /sharing` — 他のユーザーとの mind 共有
- `POST /push/subscribe` — Web Push 通知の購読
- `GET /sharing` — mind 共有の一覧

### JWT でできないこと

- メモリの読み書き（Mind Key が必要）
- チャットメッセージの送信（Mind Key が必要）
- タスク管理（Mind Key が必要）
- Webhook の登録（Mind Key が必要）

## 特殊ケース：Computer Token

`/computers/me/*` エンドポイント（エージェント向け、screen-remote-agent 用）は第 3 のトークン種別である **Computer Token** を使用します。このトークンはインストールコードを引き換える際に `POST /computers/register` が返し、1 つの登録済みコンピュータに固有です。

| エンドポイント | 認証 |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key または JWT |
| `POST /computers/:id/commands` | Mind Key または JWT |

## よくあるパターン

### パターン 1：単一 LLM エージェント

1. 一度登録 → JWT を取得
2. 1 つの mind を作成 → Mind Key を取得
3. LLM はすべてに Mind Key を使用

### パターン 2：マルチプロジェクトエージェント

1. 一度登録 → JWT を取得
2. 複数の mind を作成（work、personal、project-x）→ 複数の Mind Key を取得
3. LLM はコンテキストに応じて異なる Mind Key を読み込み

### パターン 3：チーム共有

1. ユーザー A が mind を作成 → Mind Key A を取得
2. ユーザー A が JWT でユーザー B と共有（`POST /sharing`）
3. ユーザー B は自身の JWT でアクセス可能
4. LLM アクセスには、ユーザー B は自身の Mind Key を作成する必要がある（または A のものを使用）

### パターン 4：MCP サーバー

MCP サーバーは常に Mind Key を使用します（`SYNAPSE_MIND_KEY` 環境変数で設定）。1 つの MCP サーバーインスタンス = 1 つの mind。マルチ mind アクセスには、複数の MCP インスタンスを動かすか、クライアント側で mind 切り替えを実装してください。

## トークン形式のチートシート

| トークン | 形式 | 例 |
|-------|--------|---------|
| Mind Key | `mk_` + 36 文字 | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 文字 | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## 次のステップ

- [Authentication](/docs/getting-started/authentication) — 完全な認証ガイド
- [User & Minds API](/docs/api/user) — JWT で保護されたエンドポイント
- [Memory API](/docs/api/memory) — Mind Key で保護されたエンドポイント