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

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

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

กฎง่าย ๆ

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 ที่ลงทะเบียนหนึ่งเครื่อง

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

รูปแบบ 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

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

• Authentication — คู่มือ auth แบบเต็ม
• User & Minds API — endpoint ที่ป้องกันด้วย JWT
• Memory API — endpoint ที่ป้องกันด้วย Mind Key