Mind Key vs JWT — Khi nào dùng cái nào?

Synapse có hai token xác thực. Chọn sai dẫn đến lỗi 401. Hướng dẫn này cung cấp cho bạn khung quyết định rõ ràng.

Bảng quyết định nhanh

Quy tắc đơn giản

Mind Key — Token truy cập dữ liệu

Mind Key cấp quyền truy cập dữ liệu của một mind. Đây là token tồn tại lâu dài, không bao giờ hết hạn (cho đến khi mind bị xóa). Hoàn hảo cho:

• LLM agent lưu trữ bộ nhớ qua các phiên
• Cron job nền
• Cấu hình MCP server
• Tích hợp webhook
• Ứng dụng di động đọc bộ nhớ

Mind Key có thể làm gì

• GET /memory/recall — đọc tất cả bộ nhớ trong mind này
• POST /memory — lưu/cập nhật bộ nhớ
• GET /chat/poll — đọc tin nhắn chat
• POST /chat/reply — gửi tin nhắn chat
• GET /mind/tasks — liệt kê tác vụ
• POST /mind/task — tạo tác vụ
• POST /script — lưu script
• POST /webhooks — đăng ký webhook
• POST /computers/:id/commands — xếp hàng lệnh máy tính

Mind Key KHÔNG THỂ làm gì

• Tạo / liệt kê / xóa mind (cần JWT)
• Chia sẻ mind với người dùng khác (cần JWT)
• Xem thông tin tài khoản người dùng (cần JWT)
• Đăng ký web push (cần JWT)

JWT — Token quản lý tài khoản

JWT xác thực tài khoản người dùng. Nó hết hạn sau 7 ngày và được sử dụng cho thao tác cấp tài khoản bao trùm nhiều mind hoặc liên quan đến người dùng khác.

JWT có thể làm gì

• POST /minds — tạo mind mới (trả về Mind Key mới)
• GET /minds — liệt kê tất cả mind của người dùng này
• DELETE /minds/:id — xóa mind
• POST /sharing — chia sẻ mind với người dùng khác
• POST /push/subscribe — đăng ký thông báo web push
• GET /sharing — liệt kê chia sẻ mind

JWT KHÔNG THỂ làm gì

• Đọc / ghi bộ nhớ (cần Mind Key)
• Gửi tin nhắn chat (cần Mind Key)
• Quản lý tác vụ (cần Mind Key)
• Đăng ký webhook (cần Mind Key)

Trường hợp đặc biệt: Computer Token

Các endpoint /computers/me/* (phía agent, cho screen-remote-agent) sử dụng loại token thứ ba: Computer Token. Token này được trả về bởi POST /computers/register khi đổi mã cài đặt, và là cụ thể cho một máy tính đã đăng ký.

Mẫu phổ biến

Mẫu 1: LLM Agent đơn

1. Đăng ký một lần → lấy JWT
2. Tạo một mind → lấy Mind Key
3. LLM sử dụng Mind Key cho mọi thứ

Mẫu 2: Agent đa dự án

1. Đăng ký một lần → lấy JWT
2. Tạo nhiều mind (work, personal, project-x) → lấy nhiều Mind Key
3. LLM tải Mind Key khác nhau dựa trên ngữ cảnh

Mẫu 3: Chia sẻ nhóm

1. Người dùng A tạo mind → lấy Mind Key A
2. Người dùng A chia sẻ với Người dùng B qua JWT (POST /sharing)
3. Người dùng B giờ có thể truy cập qua JWT của họ
4. Cho truy cập LLM, Người dùng B cần tạo Mind Key riêng (hoặc dùng của A)

Mẫu 4: MCP Server

MCP server luôn sử dụng Mind Key (đặt qua biến môi trường SYNAPSE_MIND_KEY). Một thể hiện MCP server = một mind. Cho truy cập đa mind, chạy nhiều thể hiện MCP hoặc triển khai chuyển đổi mind phía client.

Bảng tham chiếu định dạng token

Bước tiếp theo

• Xác thực — hướng dẫn xác thực đầy đủ
• User & Minds API — endpoint được bảo vệ JWT
• Memory API — endpoint được bảo vệ Mind Key