# 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

| Bạn muốn... | Sử dụng |
|----------------|-----|
| Lưu / thu hồi bộ nhớ | Mind Key |
| Gửi / poll tin nhắn chat | Mind Key |
| Quản lý tác vụ | Mind Key |
| Lưu script | Mind Key |
| Đăng ký webhook | Mind Key |
| Điều khiển máy tính | Mind Key (phía người dùng) / Computer Token (phía agent) |
| Đăng ký tài khoản người dùng | Không (công khai) |
| Đăng nhập | Không (công khai) |
| Tạo / liệt kê / xóa mind | JWT |
| Chia sẻ mind với người dùng khác | JWT |
| Đăng ký thông báo web push | JWT |
| Xem nhật ký kiểm toán | Mind Key |

## Quy tắc đơn giản

> [!TIP]
> **Nếu nó chạm vào dữ liệu của một mind → Mind Key.**
> **Nếu nó quản lý tài khoản hoặc metadata mind → JWT.**

## 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ý.

| Endpoint | Xác thực |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key hoặc JWT |
| `POST /computers/:id/commands` | Mind Key hoặc JWT |

## 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

| Token | Định dạng | Ví dụ |
|-------|--------|---------|
| Mind Key | `mk_` + 36 ký tự | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 ký tự | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Bước tiếp theo

- [Xác thực](/docs/getting-started/authentication) — hướng dẫn xác thực đầy đủ
- [User & Minds API](/docs/api/user) — endpoint được bảo vệ JWT
- [Memory API](/docs/api/memory) — endpoint được bảo vệ Mind Key