{"title":"认证与 Mind Key","slug":"authentication","category":"getting-started","summary":"Synapse 认证机制：Agent 用 Mind Key，人类用 JWT，只能用 URL 的工具用 ?key=。","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":274,"read_minutes":1,"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":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 认证与 Mind Key\n\nSynapse 使用两种认证方法，各自针对不同用例优化。理解它们的区别对构建可靠集成至关重要。\n\n## 两种认证方法\n\n| 方法 | 用例 | 限速 | 过期 |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM Agent、自动化工具 | 无（header）/ 60 次/分钟（query） | 永不过期 |\n| **JWT** | 人类界面 UI、账户操作 | 无 | 7 天 |\n\n## Mind Key（用于 Agent）\n\nMind Key 是租户范围的 API 令牌。它对单个 Mind 的数据（记忆、任务、聊天、脚本等）进行认证。适用于：\n\n- 调用 API 的 LLM Agent\n- 后台自动化脚本\n- MCP Server 配置\n- 任何长期集成\n\n### 头部认证（推荐）\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### 查询参数（用于只能用 URL 的工具）\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> `?key=` 查询参数被限速为**每分钟 60 次请求**。Bearer 头无限制。客户端支持自定义请求头时，请始终使用请求头。\n\n### 创建 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\n响应包含 `mind_key` — **请立即保存**，它只显示一次。\n\n### 列出你的 Mind\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### 删除 Mind（不可逆！）\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT（用于人类）\n\nJWT 对**用户账户**进行认证，而非特定 Mind。用于：\n\n- 账户注册与登录\n- 创建/列出/删除 Mind\n- 与其他用户共享 Mind\n- Web Push 订阅管理\n\n### 注册\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\n返回：`{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### 登录\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\n返回：`{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### JWT 过期\n\nJWT 在 **7 天**后过期。过期后再次调用 `/login` 即可获取新 JWT。Mind Key 永不过期，因此现有 Agent 集成可继续工作。\n\n## 安全最佳实践\n\n> [!CRITICAL]\n> - **绝不把 Mind Key 提交到 git。** 使用环境变量。\n> - **绝不在日志中记录 Mind Key。** 在日志中遮蔽（`mk_***...***xyz`）。\n> - **怀疑泄露时轮换 key**（删除 Mind、创建新 Mind）。\n> - **每个项目用一个 Mind**，以缩小 key 泄露的爆炸半径。\n\n### 环境变量模式\n\n```bash\n# .env（绝不提交此文件）\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### 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## 多 Mind 模式\n\n每个用户可有多个 Mind。常见模式：\n\n| Mind 名称 | 用途 |\n|-----------|---------|\n| `work` | 工作相关记忆 |\n| `personal` | 个人偏好、家庭 |\n| `project-synapse` | 特定项目上下文 |\n| `learning-german` | 学习进度 |\n| `assistant-default` | 通用回退 |\n\n在不同 LLM 会话中使用不同 Mind Key 即可隔离上下文。\n\n## 限速\n\n| 认证方式 | 限制 | 范围 |\n|-------------|-------|-------|\n| Mind Key（header） | 无 | 每个 Mind |\n| Mind Key（?key=） | 60 次/分钟 | 每个 IP |\n| JWT（header） | 无 | 每个用户 |\n| 公共端点 | 无 | 全局 |\n\n如适用，响应会包含限速头（`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`Retry-After`）。\n\n## 下一步\n\n- [Mind Key 与 JWT](/docs/getting-started/mind-key-vs-jwt) — 何时用哪个\n- [Memory API](/docs/api/memory) — 用 Mind Key 能做什么\n- [User API](/docs/api/user) — 用 JWT 进行账户管理\n","content_html":"

认证与 Mind Key

\n

Synapse 使用两种认证方法，各自针对不同用例优化。理解它们的区别对构建可靠集成至关重要。

\n

两种认证方法

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方法用例限速过期
Mind KeyLLM Agent、自动化工具无（header）/ 60 次/分钟（query）永不过期
JWT人类界面 UI、账户操作无7 天
\n

Mind Key（用于 Agent）

\n

Mind Key 是租户范围的 API 令牌。它对单个 Mind 的数据（记忆、任务、聊天、脚本等）进行认证。适用于：

\n\n

头部认证（推荐）

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

查询参数（用于只能用 URL 的工具）

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
`?key=` 查询参数被限速为**每分钟 60 次请求**。Bearer 头无限制。客户端支持自定义请求头时，请始终使用请求头。

创建 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"}'

响应包含 mind_key — 请立即保存，它只显示一次。

\n

列出你的 Mind

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

删除 Mind（不可逆！）

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

JWT（用于人类）

\n

JWT 对用户账户进行认证，而非特定 Mind。用于：

\n\n

注册

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

返回：{ "jwt": "eyJ...", "user": {...} }

\n

登录

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

返回：{ "jwt": "eyJ...", "user": {...} }

\n

JWT 过期

\n

JWT 在 7 天后过期。过期后再次调用 /login 即可获取新 JWT。Mind Key 永不过期，因此现有 Agent 集成可继续工作。

\n

安全最佳实践

\n

环境变量模式

\n
# .env（绝不提交此文件）\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});

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}

多 Mind 模式

\n

每个用户可有多个 Mind。常见模式：

\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
Mind 名称用途
work工作相关记忆
personal个人偏好、家庭
project-synapse特定项目上下文
learning-german学习进度
assistant-default通用回退
\n

在不同 LLM 会话中使用不同 Mind Key 即可隔离上下文。

\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\n
认证方式限制范围
Mind Key（header）无每个 Mind
Mind Key（?key=）60 次/分钟每个 IP
JWT（header）无每个用户
公共端点无全局
\n

如适用，响应会包含限速头（X-RateLimit-Limit、X-RateLimit-Remaining、Retry-After）。

\n

下一步

\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"]}