# Mind Key vs JWT — ใช้เมื่อไร?

Synapse มีสอง authentication token การเลือกผิดจะนำไปสู่ error 401 คู่มือนี้ให้กรอบการตัดสินใจที่ชัดเจน

## ตารางการตัดสินใจด่วน

| คุณต้องการ... | ใช้ |
|----------------|-----|
| จัดเก็บ / recall memory | Mind Key |
| ส่ง / poll ข้อความแช็ต | Mind Key |
| จัดการ task | Mind Key |
| เก็บ script | Mind Key |
| ลงทะเบียน webhook | Mind Key |
| ควบคุม computer | Mind Key (ฝั่งผู้ใช้) / Computer Token (ฝั่ง agent) |
| สมัครบัญชีผู้ใช้ | None (public) |
| ล็อกอิน | None (public) |
| สร้าง / รายการ / ลบ mind | JWT |
| แชร์ mind กับผู้ใช้อื่น | JWT |
| สมัครรับ web push notification | JWT |
| ดู audit log | Mind Key |

## กฎง่าย ๆ

> [!TIP]
> **หากมันสัมผัสข้อมูล mind เดียว → Mind Key**
> **หากมันจัดการบัญชีหรือ metadata ของ mind → JWT**

## Mind Key — Data Access Token

Mind Key ให้สิทธิ์เข้าถึง **ข้อมูล mind หนึ่ง** เป็น token ที่อยู่ยาวนานและไม่หมดอายุ (จนกว่า mind จะถูกลบ) เหมาะสำหรับ:

- LLM agent ที่เก็บ memory ข้าม session
- cron job เบื้องหลัง
- กำหนดค่า MCP server
- integration webhook
- แอปมือถือที่อ่าน memory

### Mind Key ทำอะไรได้

- `GET /memory/recall` — อ่าน memory ทั้งหมดใน mind นี้
- `POST /memory` — เก็บ/อัปเดต memory
- `GET /chat/poll` — อ่านข้อความแช็ต
- `POST /chat/reply` — ส่งข้อความแช็ต
- `GET /mind/tasks` — รายการ task
- `POST /mind/task` — สร้าง task
- `POST /script` — เก็บ script
- `POST /webhooks` — ลงทะเบียน webhook
- `POST /computers/:id/commands` — จัดคิวคำสั่ง computer

### Mind Key ทำอะไรไม่ได้

- สร้าง / รายการ / ลบ mind (ต้องใช้ JWT)
- แชร์ mind กับผู้ใช้อื่น (ต้องใช้ JWT)
- ดูข้อมูลบัญชีผู้ใช้ (ต้องใช้ JWT)
- สมัครรับ web push (ต้องใช้ JWT)

## JWT — Account Management Token

JWT ยืนยันตัวตน **บัญชีผู้ใช้** หมดอายุหลัง 7 วัน และใช้สำหรับการดำเนินการระดับบัญชีที่ครอบคลุมหลาย mind หรือเกี่ยวข้องกับผู้ใช้อื่น

### JWT ทำอะไรได้

- `POST /minds` — สร้าง mind ใหม่ (ส่งกลับ Mind Key ใหม่)
- `GET /minds` — รายการ mind ทั้งหมดของผู้ใช้นี้
- `DELETE /minds/:id` — ลบ mind
- `POST /sharing` — แชร์ mind กับผู้ใช้อื่น
- `POST /push/subscribe` — สมัครรับ web push notification
- `GET /sharing` — รายการการแชร์ mind

### JWT ทำอะไรไม่ได้

- อ่าน / เขียน memory (ต้องใช้ Mind Key)
- ส่งข้อความแช็ต (ต้องใช้ Mind Key)
- จัดการ task (ต้องใช้ Mind Key)
- ลงทะเบียน webhook (ต้องใช้ Mind Key)

## กรณีพิเศษ: Computer Token

endpoint `/computers/me/*` (ฝั่ง agent, สำหรับ screen-remote-agent) ใช้ token ประเภทที่สาม: **Computer Token** token นี้ถูกส่งกลับโดย `POST /computers/register` เมื่อแลกรับ install code และเฉพาะสำหรับ computer ที่ลงทะเบียนหนึ่งเครื่อง

| Endpoint | Auth |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key or JWT |
| `POST /computers/:id/commands` | Mind Key or JWT |

## รูปแบบทั่วไป

### รูปแบบ 1: LLM Agent เดียว

1. สมัครครั้งเดียว → รับ JWT
2. สร้าง mind เดียว → รับ Mind Key
3. LLM ใช้ Mind Key สำหรับทุกอย่าง

### รูปแบบ 2: Agent หลายโปรเจกต์

1. สมัครครั้งเดียว → รับ JWT
2. สร้างหลาย mind (work, personal, project-x) → รับหลาย Mind Key
3. LLM โหลด Mind Key ต่างกันตาม context

### รูปแบบ 3: การแชร์ในทีม

1. ผู้ใช้ A สร้าง mind → ได้ Mind Key A
2. ผู้ใช้ A แชร์กับผู้ใช้ B ผ่าน JWT (`POST /sharing`)
3. ผู้ใช้ B สามารถเข้าถึงผ่าน JWT ของตนเอง
4. สำหรับการเข้าถึง LLM, ผู้ใช้ B ต้องสร้าง Mind Key ของตนเอง (หรือใช้ของ A)

### รูปแบบ 4: MCP Server

MCP server ใช้ Mind Key เสมอ (ตั้งผ่าน env var `SYNAPSE_MIND_KEY`) หนึ่ง MCP server instance = หนึ่ง mind สำหรับการเข้าถึงหลาย mind ให้รันหลาย MCP instance หรือ implement mind switching ฝั่ง client

## Cheat Sheet รูปแบบ Token

| Token | รูปแบบ | ตัวอย่าง |
|-------|--------|---------|
| Mind Key | `mk_` + 36 ตัวอักษร | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 ตัวอักษร | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## ขั้นตอนถัดไป

- [Authentication](/docs/getting-started/authentication) — คู่มือ auth แบบเต็ม
- [User & Minds API](/docs/api/user) — endpoint ที่ป้องกันด้วย JWT
- [Memory API](/docs/api/memory) — endpoint ที่ป้องกันด้วย Mind Key