{"title":"Xác thực & Mind Key","slug":"authentication","category":"getting-started","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.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":638,"read_minutes":3,"llm_context":"Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).\nMind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)\nJWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)\nMind Key is shown only once at creation. Store it permanently.\nEach mind has exactly one Mind Key. Multiple minds = multiple keys.\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Xác thực & Mind Key\n\nSynapse 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\ntrườ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\ntích hợp đáng tin cậy.\n\n## Hai phương thức xác thực\n\n| Phương thức | Trường hợp | Giới hạn tốc độ | Hết hạn |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM agent, công cụ tự động | Không (header) / 60 phút (query) | Không bao giờ |\n| **JWT** | Giao diện hướng con người, thao tác tài khoản | Không | 7 ngày |\n\n## Mind Key (cho Agent)\n\nMind Key là token API phạm vi tenant. Nó xác thực dữ liệu của một mind duy nhất\n(bộ nhớ, tác vụ, chat, script, v.v.). Sử dụng nó cho:\n\n- LLM agent gọi API\n- Script tự động hóa nền\n- Cấu hình MCP server\n- Bất kỳ tích hợp tồn tại lâu dài nào\n\n### Xác thực header (khuyến nghị)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Tham số query (cho công cụ chỉ dùng URL)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Tham số query `?key=` bị giới hạn tốc độ **60 yêu cầu mỗi phút**. Header\n> 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\n> hỗ trợ header tùy chỉnh.\n\n### Tạo Mind Key\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/minds \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Work Mind\", \"description\": \"Project memories\"}'\n```\n\nPhản hồi bao gồm `mind_key` — **lưu ngay lập tức**, nó chỉ hiển thị một lần.\n\n### Liệt kê mind của bạn\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Xóa mind (không thể đảo ngược!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (cho Con người)\n\nJWT 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:\n\n- Đăng ký và đăng nhập tài khoản\n- Tạo / liệt kê / xóa mind\n- Chia sẻ mind với người dùng khác\n- Quản lý đăng ký Web Push\n\n### Đăng ký\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nTrả về: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Đăng nhập\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nTrả về: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Hết hạn JWT\n\nJWT hết hạn sau **7 ngày**. Khi JWT hết hạn, chỉ cần gọi lại `/login` để lấy\nJWT 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\ntục hoạt động.\n\n## Thực hành bảo mật tốt nhất\n\n> [!CRITICAL]\n> - **Không bao giờ commit Mind Key vào git.** Sử dụng biến môi trường.\n> - **Không bao giờ ghi nhật ký Mind Key.** Che chúng trong nhật ký (`mk_***...***xyz`).\n> - **Xoay vòng key** nếu bạn nghi ngờ lộ lọt (xóa mind, tạo mới).\n> - **Sử dụng một mind mỗi dự án** để giới hạn thiệt hại nếu key bị lộ.\n\n### Mẫu biến môi trường\n\n```bash\n# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone\n```\n\n```typescript\n// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n headers: { Authorization: `Bearer ${mindKey}` },\n});\n```\n\n### Cấu hình MCP server\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_yourMindKeyHere\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n## Mẫu Multi-Mind\n\nMỗi người dùng có thể có nhiều mind. Mẫu phổ biến:\n\n| Tên Mind | Mục đích |\n|-----------|---------|\n| `work` | Bộ nhớ liên quan công việc |\n| `personal` | Sở thích cá nhân, gia đình |\n| `project-synapse` | Ngữ cảnh dự án cụ thể |\n| `learning-german` | Tiến độ học tập |\n| `assistant-default` | Fallback mục đích chung |\n\nSử dụng các Mind Key khác nhau cho các phiên LLM khác nhau để giữ ngữ cảnh tách\nbiệt.\n\n## Giới hạn tốc độ\n\n| Phương thức xác thực | Giới hạn | Phạm vi |\n|-------------|-------|-------|\n| Mind Key (header) | Không | Mỗi mind |\n| Mind Key (?key=) | 60/phút | Mỗi IP |\n| JWT (header) | Không | Mỗi người dùng |\n| Endpoint công khai | Không | Toàn cầu |\n\nHeader giới hạn tốc độ (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,\n`Retry-After`) được bao gồm trong phản hồi khi áp dụng.\n\n## Bước tiếp theo\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — khi nào dùng cái nào\n- [Memory API](/docs/api/memory) — những gì bạn có thể làm với Mind Key\n- [User API](/docs/api/user) — quản lý tài khoản với JWT\n","content_html":"

Xác thực & Mind Key

\n

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\ntrườ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\ntích hợp đáng tin cậy.

\n

Hai phương thức xác thực

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Phương thứcTrường hợpGiới hạn tốc độHết hạn
Mind KeyLLM agent, công cụ tự độngKhông (header) / 60 phút (query)Không bao giờ
JWTGiao diện hướng con người, thao tác tài khoảnKhông7 ngày
\n

Mind Key (cho Agent)

\n

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\n(bộ nhớ, tác vụ, chat, script, v.v.). Sử dụng nó cho:

\n\n

Xác thực header (khuyến nghị)

\n
curl -H "Authorization: Bearer mk_yourMindKeyHere" \\\n     https://synapse.schaefer.zone/memory/recall

Tham số query (cho công cụ chỉ dùng URL)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
Tham số query `?key=` bị giới hạn tốc độ **60 yêu cầu mỗi phút**. Header\nBearer không có giới hạn tốc độ. Sử dụng header bất cứ khi nào client của bạn\nhỗ trợ header tùy chỉnh.

Tạo Mind Key

\n
curl -X POST https://synapse.schaefer.zone/minds \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"name": "Work Mind", "description": "Project memories"}'

Phản hồi bao gồm mind_key — lưu ngay lập tức, nó chỉ hiển thị một lần.

\n

Liệt kê mind của bạn

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds

Xóa mind (không thể đảo ngược!)

\n
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds/m_xyz789

JWT (cho Con người)

\n

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:

\n\n

Đăng ký

\n
curl -X POST https://synapse.schaefer.zone/register \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Trả về: { "jwt": "eyJ...", "user": {...} }

\n

Đăng nhập

\n
curl -X POST https://synapse.schaefer.zone/login \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Trả về: { "jwt": "eyJ...", "user": {...} }

\n

Hết hạn JWT

\n

JWT hết hạn sau 7 ngày. Khi JWT hết hạn, chỉ cần gọi lại /login để lấy\nJWT 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\ntục hoạt động.

\n

Thực hành bảo mật tốt nhất

\n

Mẫu biến môi trường

\n
# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone
// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n  headers: { Authorization: `Bearer ${mindKey}` },\n});

Cấu hình MCP server

\n
{\n  "mcpServers": {\n    "synapse": {\n      "command": "npx",\n      "args": ["-y", "synapse-mcp-api@latest"],\n      "env": {\n        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",\n        "SYNAPSE_URL": "https://synapse.schaefer.zone"\n      }\n    }\n  }\n}

Mẫu Multi-Mind

\n

Mỗi người dùng có thể có nhiều mind. Mẫu phổ biến:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Tên MindMục đích
workBộ nhớ liên quan công việc
personalSở thích cá nhân, gia đình
project-synapseNgữ cảnh dự án cụ thể
learning-germanTiến độ học tập
assistant-defaultFallback mục đích chung
\n

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\nbiệt.

\n

Giới hạn tốc độ

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Phương thức xác thựcGiới hạnPhạm vi
Mind Key (header)KhôngMỗi mind
Mind Key (?key=)60/phútMỗi IP
JWT (header)KhôngMỗi người dùng
Endpoint công khaiKhôngToàn cầu
\n

Header giới hạn tốc độ (X-RateLimit-Limit, X-RateLimit-Remaining,\nRetry-After) được bao gồm trong phản hồi khi áp dụng.

\n

Bước tiếp theo

\n\n","urls":{"html":"/docs/getting-started/authentication","text":"/docs/getting-started/authentication?format=text","json":"/docs/getting-started/authentication?format=json","llm":"/docs/getting-started/authentication?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}