{"title":"Mind Key vs JWT — Khi nào dùng cái nào?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Hướng dẫn quyết định: Mind Key cho truy cập dữ liệu agent, JWT cho quản lý tài khoản.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":831,"read_minutes":4,"llm_context":"Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.\nJWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.\nSimple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.\nException: /computers/me/* uses Computer Token (not Mind Key or JWT).\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Mind Key vs JWT — Khi nào dùng cái nào?\n\nSynapse 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\ncho bạn khung quyết định rõ ràng.\n\n## Bảng quyết định nhanh\n\n| Bạn muốn... | Sử dụng |\n|----------------|-----|\n| Lưu / thu hồi bộ nhớ | Mind Key |\n| Gửi / poll tin nhắn chat | Mind Key |\n| Quản lý tác vụ | Mind Key |\n| Lưu script | Mind Key |\n| Đăng ký webhook | Mind Key |\n| Điều khiển máy tính | Mind Key (phía người dùng) / Computer Token (phía agent) |\n| Đăng ký tài khoản người dùng | Không (công khai) |\n| Đăng nhập | Không (công khai) |\n| Tạo / liệt kê / xóa mind | JWT |\n| Chia sẻ mind với người dùng khác | JWT |\n| Đăng ký thông báo web push | JWT |\n| Xem nhật ký kiểm toán | Mind Key |\n\n## Quy tắc đơn giản\n\n> [!TIP]\n> **Nếu nó chạm vào dữ liệu của một mind → Mind Key.**\n> **Nếu nó quản lý tài khoản hoặc metadata mind → JWT.**\n\n## Mind Key — Token truy cập dữ liệu\n\nMind 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\ndài, không bao giờ hết hạn (cho đến khi mind bị xóa). Hoàn hảo cho:\n\n- LLM agent lưu trữ bộ nhớ qua các phiên\n- Cron job nền\n- Cấu hình MCP server\n- Tích hợp webhook\n- Ứng dụng di động đọc bộ nhớ\n\n### Mind Key có thể làm gì\n\n- `GET /memory/recall` — đọc tất cả bộ nhớ trong mind này\n- `POST /memory` — lưu/cập nhật bộ nhớ\n- `GET /chat/poll` — đọc tin nhắn chat\n- `POST /chat/reply` — gửi tin nhắn chat\n- `GET /mind/tasks` — liệt kê tác vụ\n- `POST /mind/task` — tạo tác vụ\n- `POST /script` — lưu script\n- `POST /webhooks` — đăng ký webhook\n- `POST /computers/:id/commands` — xếp hàng lệnh máy tính\n\n### Mind Key KHÔNG THỂ làm gì\n\n- Tạo / liệt kê / xóa mind (cần JWT)\n- Chia sẻ mind với người dùng khác (cần JWT)\n- Xem thông tin tài khoản người dùng (cần JWT)\n- Đăng ký web push (cần JWT)\n\n## JWT — Token quản lý tài khoản\n\nJWT 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\ncho 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.\n\n### JWT có thể làm gì\n\n- `POST /minds` — tạo mind mới (trả về Mind Key mới)\n- `GET /minds` — liệt kê tất cả mind của người dùng này\n- `DELETE /minds/:id` — xóa mind\n- `POST /sharing` — chia sẻ mind với người dùng khác\n- `POST /push/subscribe` — đăng ký thông báo web push\n- `GET /sharing` — liệt kê chia sẻ mind\n\n### JWT KHÔNG THỂ làm gì\n\n- Đọc / ghi bộ nhớ (cần Mind Key)\n- Gửi tin nhắn chat (cần Mind Key)\n- Quản lý tác vụ (cần Mind Key)\n- Đăng ký webhook (cần Mind Key)\n\n## Trường hợp đặc biệt: Computer Token\n\nCác endpoint `/computers/me/*` (phía agent, cho screen-remote-agent) sử dụng\nloại token thứ ba: **Computer Token**. Token này được trả về bởi\n`POST /computers/register` khi đổi mã cài đặt, và là cụ thể cho một máy tính đã\nđăng ký.\n\n| Endpoint | Xác thực |\n|----------|------|\n| `GET /computers/me/poll` | Computer Token |\n| `POST /computers/me/commands/:cid/result` | Computer Token |\n| `GET /computers/list` | Mind Key hoặc JWT |\n| `POST /computers/:id/commands` | Mind Key hoặc JWT |\n\n## Mẫu phổ biến\n\n### Mẫu 1: LLM Agent đơn\n\n1. Đăng ký một lần → lấy JWT\n2. Tạo một mind → lấy Mind Key\n3. LLM sử dụng Mind Key cho mọi thứ\n\n### Mẫu 2: Agent đa dự án\n\n1. Đăng ký một lần → lấy JWT\n2. Tạo nhiều mind (work, personal, project-x) → lấy nhiều Mind Key\n3. LLM tải Mind Key khác nhau dựa trên ngữ cảnh\n\n### Mẫu 3: Chia sẻ nhóm\n\n1. Người dùng A tạo mind → lấy Mind Key A\n2. Người dùng A chia sẻ với Người dùng B qua JWT (`POST /sharing`)\n3. Người dùng B giờ có thể truy cập qua JWT của họ\n4. 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)\n\n### Mẫu 4: MCP Server\n\nMCP server luôn sử dụng Mind Key (đặt qua biến môi trường\n`SYNAPSE_MIND_KEY`). Một thể hiện MCP server = một mind. Cho truy cập đa mind,\nchạy nhiều thể hiện MCP hoặc triển khai chuyển đổi mind phía client.\n\n## Bảng tham chiếu định dạng token\n\n| Token | Định dạng | Ví dụ |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36 ký tự | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 ký tự | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Bước tiếp theo\n\n- [Xác thực](/docs/getting-started/authentication) — hướng dẫn xác thực đầy đủ\n- [User & Minds API](/docs/api/user) — endpoint được bảo vệ JWT\n- [Memory API](/docs/api/memory) — endpoint được bảo vệ Mind Key\n","content_html":"<h1>Mind Key vs JWT — Khi nào dùng cái nào?</h1>\n<p>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\ncho bạn khung quyết định rõ ràng.</p>\n<h2>Bảng quyết định nhanh</h2>\n<table>\n<thead>\n<tr>\n<th>Bạn muốn...</th>\n<th>Sử dụng</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Lưu / thu hồi bộ nhớ</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Gửi / poll tin nhắn chat</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Quản lý tác vụ</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Lưu script</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Đăng ký webhook</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Điều khiển máy tính</td>\n<td>Mind Key (phía người dùng) / Computer Token (phía agent)</td>\n</tr>\n<tr>\n<td>Đăng ký tài khoản người dùng</td>\n<td>Không (công khai)</td>\n</tr>\n<tr>\n<td>Đăng nhập</td>\n<td>Không (công khai)</td>\n</tr>\n<tr>\n<td>Tạo / liệt kê / xóa mind</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Chia sẻ mind với người dùng khác</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Đăng ký thông báo web push</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Xem nhật ký kiểm toán</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>Quy tắc đơn giản</h2>\n<div class=\"callout callout-ok\">**Nếu nó chạm vào dữ liệu của một mind → Mind Key.**\n**Nếu nó quản lý tài khoản hoặc metadata mind → JWT.**</div><h2>Mind Key — Token truy cập dữ liệu</h2>\n<p>Mind Key cấp quyền truy cập <strong>dữ liệu của một mind</strong>. Đây là token tồn tại lâu\ndài, không bao giờ hết hạn (cho đến khi mind bị xóa). Hoàn hảo cho:</p>\n<ul>\n<li>LLM agent lưu trữ bộ nhớ qua các phiên</li>\n<li>Cron job nền</li>\n<li>Cấu hình MCP server</li>\n<li>Tích hợp webhook</li>\n<li>Ứng dụng di động đọc bộ nhớ</li>\n</ul>\n<h3>Mind Key có thể làm gì</h3>\n<ul>\n<li><code>GET /memory/recall</code> — đọc tất cả bộ nhớ trong mind này</li>\n<li><code>POST /memory</code> — lưu/cập nhật bộ nhớ</li>\n<li><code>GET /chat/poll</code> — đọc tin nhắn chat</li>\n<li><code>POST /chat/reply</code> — gửi tin nhắn chat</li>\n<li><code>GET /mind/tasks</code> — liệt kê tác vụ</li>\n<li><code>POST /mind/task</code> — tạo tác vụ</li>\n<li><code>POST /script</code> — lưu script</li>\n<li><code>POST /webhooks</code> — đăng ký webhook</li>\n<li><code>POST /computers/:id/commands</code> — xếp hàng lệnh máy tính</li>\n</ul>\n<h3>Mind Key KHÔNG THỂ làm gì</h3>\n<ul>\n<li>Tạo / liệt kê / xóa mind (cần JWT)</li>\n<li>Chia sẻ mind với người dùng khác (cần JWT)</li>\n<li>Xem thông tin tài khoản người dùng (cần JWT)</li>\n<li>Đăng ký web push (cần JWT)</li>\n</ul>\n<h2>JWT — Token quản lý tài khoản</h2>\n<p>JWT xác thực <strong>tài khoản người dùng</strong>. Nó hết hạn sau 7 ngày và được sử dụng\ncho 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.</p>\n<h3>JWT có thể làm gì</h3>\n<ul>\n<li><code>POST /minds</code> — tạo mind mới (trả về Mind Key mới)</li>\n<li><code>GET /minds</code> — liệt kê tất cả mind của người dùng này</li>\n<li><code>DELETE /minds/:id</code> — xóa mind</li>\n<li><code>POST /sharing</code> — chia sẻ mind với người dùng khác</li>\n<li><code>POST /push/subscribe</code> — đăng ký thông báo web push</li>\n<li><code>GET /sharing</code> — liệt kê chia sẻ mind</li>\n</ul>\n<h3>JWT KHÔNG THỂ làm gì</h3>\n<ul>\n<li>Đọc / ghi bộ nhớ (cần Mind Key)</li>\n<li>Gửi tin nhắn chat (cần Mind Key)</li>\n<li>Quản lý tác vụ (cần Mind Key)</li>\n<li>Đăng ký webhook (cần Mind Key)</li>\n</ul>\n<h2>Trường hợp đặc biệt: Computer Token</h2>\n<p>Các endpoint <code>/computers/me/*</code> (phía agent, cho screen-remote-agent) sử dụng\nloại token thứ ba: <strong>Computer Token</strong>. Token này được trả về bởi\n<code>POST /computers/register</code> khi đổi mã cài đặt, và là cụ thể cho một máy tính đã\nđăng ký.</p>\n<table>\n<thead>\n<tr>\n<th>Endpoint</th>\n<th>Xác thực</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /computers/me/poll</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>POST /computers/me/commands/:cid/result</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>GET /computers/list</code></td>\n<td>Mind Key hoặc JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key hoặc JWT</td>\n</tr>\n</tbody></table>\n<h2>Mẫu phổ biến</h2>\n<h3>Mẫu 1: LLM Agent đơn</h3>\n<ol>\n<li>Đăng ký một lần → lấy JWT</li>\n<li>Tạo một mind → lấy Mind Key</li>\n<li>LLM sử dụng Mind Key cho mọi thứ</li>\n</ol>\n<h3>Mẫu 2: Agent đa dự án</h3>\n<ol>\n<li>Đăng ký một lần → lấy JWT</li>\n<li>Tạo nhiều mind (work, personal, project-x) → lấy nhiều Mind Key</li>\n<li>LLM tải Mind Key khác nhau dựa trên ngữ cảnh</li>\n</ol>\n<h3>Mẫu 3: Chia sẻ nhóm</h3>\n<ol>\n<li>Người dùng A tạo mind → lấy Mind Key A</li>\n<li>Người dùng A chia sẻ với Người dùng B qua JWT (<code>POST /sharing</code>)</li>\n<li>Người dùng B giờ có thể truy cập qua JWT của họ</li>\n<li>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)</li>\n</ol>\n<h3>Mẫu 4: MCP Server</h3>\n<p>MCP server luôn sử dụng Mind Key (đặt qua biến môi trường\n<code>SYNAPSE_MIND_KEY</code>). Một thể hiện MCP server = một mind. Cho truy cập đa mind,\nchạy nhiều thể hiện MCP hoặc triển khai chuyển đổi mind phía client.</p>\n<h2>Bảng tham chiếu định dạng token</h2>\n<table>\n<thead>\n<tr>\n<th>Token</th>\n<th>Định dạng</th>\n<th>Ví dụ</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key</td>\n<td><code>mk_</code> + 36 ký tự</td>\n<td><code>mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789</code></td>\n</tr>\n<tr>\n<td>JWT</td>\n<td><code>eyJ</code> + base64</td>\n<td><code>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</code></td>\n</tr>\n<tr>\n<td>Computer Token</td>\n<td><code>ct_</code> + 36 ký tự</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Bước tiếp theo</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Xác thực</a> — hướng dẫn xác thực đầy đủ</li>\n<li><a href=\"/docs/api/user\">User &amp; Minds API</a> — endpoint được bảo vệ JWT</li>\n<li><a href=\"/docs/api/memory\">Memory API</a> — endpoint được bảo vệ Mind Key</li>\n</ul>\n","urls":{"html":"/docs/getting-started/mind-key-vs-jwt","text":"/docs/getting-started/mind-key-vs-jwt?format=text","json":"/docs/getting-started/mind-key-vs-jwt?format=json","llm":"/docs/getting-started/mind-key-vs-jwt?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}