# Xác thực & Mind Key
SUMMARY: Cách xác thực Synapse hoạt động: Mind Key cho agent, JWT cho con người, ?key= cho công cụ chỉ dùng URL.

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

Xác thực & Mind Key
Synapse sử dụng hai phương thức xác thực, mỗi phương thức được tối ưu cho một
trường hợp sử dụng khác nhau. Hiểu sự khác biệt là điều thiết yếu để xây dựng
tích hợp đáng tin cậy.
Hai phương thức xác thực
| Phương thức | Trường hợp | Giới hạn tốc độ | Hết hạn |
|--------|----------|------------|--------|
| Mind Key | LLM agent, công cụ tự động | Không (header) / 60 phút (query) | Không bao giờ |
| JWT | Giao diện hướng con người, thao tác tài khoản | Không | 7 ngày |
Mind Key (cho Agent)
Mind Key là token API phạm vi tenant. Nó xác thực dữ liệu của một mind duy nhất
(bộ nhớ, tác vụ, chat, script, v.v.). Sử dụng nó cho:
- LLM agent gọi API
- Script tự động hóa nền
- Cấu hình MCP server
- Bất kỳ tích hợp tồn tại lâu dài nào
Xác thực header (khuyến nghị)
[CODE BLOCK]
Tham số query (cho công cụ chỉ dùng URL)
[CODE BLOCK]
> [!WARNING]
> Tham số query  bị giới hạn tốc độ 60 yêu cầu mỗi phút. Header
> Bearer không có giới hạn tốc độ. Sử dụng header bất cứ khi nào client của bạn
> hỗ trợ header tùy chỉnh.
Tạo Mind Key
[CODE BLOCK]
Phản hồi bao gồm  — lưu ngay lập tức, nó chỉ hiển thị một lần.
Liệt kê mind của bạn
[CODE BLOCK]
Xóa mind (không thể đảo ngược!)
[CODE BLOCK]
JWT (cho Con người)
JWT xác thực tài khoản người dùng, không phải một mind cụ thể. Sử dụng cho:
- Đăng ký và đăng nhập tài khoản
- Tạo / liệt kê / xóa mind
- Chia sẻ mind với người dùng khác
- Quản lý đăng ký Web Push
Đăng ký
[CODE BLOCK]
Trả về: 
Đăng nhập
[CODE BLOCK]
Trả về: 
Hết hạn JWT
JWT hết hạn sau 7 ngày. Khi JWT hết hạn, chỉ cần gọi lại  để lấy
JWT mới. Mind Key không bao giờ hết hạn, do đó các tích hợp agent hiện tại tiếp
tục hoạt động.
Thực hành bảo mật tốt nhất
> [!CRITICAL]
> - Không bao giờ commit Mind Key vào git. Sử dụng biến môi trường.
> - Không bao giờ ghi nhật ký Mind Key. Che chúng trong nhật ký ().
> - Xoay vòng key nếu bạn nghi ngờ lộ lọt (xóa mind, tạo mới).
> - Sử dụng một mind mỗi dự án để giới hạn thiệt hại nếu key bị lộ.
Mẫu biến môi trường
[CODE BLOCK]
[CODE BLOCK]
Cấu hình MCP server
[CODE BLOCK]
Mẫu Multi-Mind
Mỗi người dùng có thể có nhiều mind. Mẫu phổ biến:
| Tên Mind | Mục đích |
|-----------|---------|
|  | Bộ nhớ liên quan công việc |
|  | Sở thích cá nhân, gia đình |
|  | Ngữ cảnh dự án cụ thể |
|  | Tiến độ học tập |
|  | Fallback mục đích chung |
Sử dụng các Mind Key khác nhau cho các phiên LLM khác nhau để giữ ngữ cảnh tách
biệt.
Giới hạn tốc độ
| Phương thức xác thực | Giới hạn | Phạm vi |
|-------------|-------|-------|
| Mind Key (header) | Không | Mỗi mind |
| Mind Key (?key=) | 60/phút | Mỗi IP |
| JWT (header) | Không | Mỗi người dùng |
| Endpoint công khai | Không | Toàn cầu |
Header giới hạn tốc độ (, ,
) được bao gồm trong phản hồi khi áp dụng.
Bước tiếp theo
- Mind Key vs JWT — khi nào dùng cái nào
- Memory API — những gì bạn có thể làm với Mind Key
- User API — quản lý tài khoản với JWT