# 认证与 Mind Key
SUMMARY: Synapse 认证机制：Agent 用 Mind Key，人类用 JWT，只能用 URL 的工具用 ?key=。

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.

认证与 Mind Key
Synapse 使用两种认证方法，各自针对不同用例优化。理解它们的区别对构建可靠集成至关重要。
两种认证方法
| 方法 | 用例 | 限速 | 过期 |
|--------|----------|------------|--------|
| Mind Key | LLM Agent、自动化工具 | 无（header）/ 60 次/分钟（query） | 永不过期 |
| JWT | 人类界面 UI、账户操作 | 无 | 7 天 |
Mind Key（用于 Agent）
Mind Key 是租户范围的 API 令牌。它对单个 Mind 的数据（记忆、任务、聊天、脚本等）进行认证。适用于：
- 调用 API 的 LLM Agent
- 后台自动化脚本
- MCP Server 配置
- 任何长期集成
头部认证（推荐）
[CODE BLOCK]
查询参数（用于只能用 URL 的工具）
[CODE BLOCK]
> [!WARNING]
>  查询参数被限速为每分钟 60 次请求。Bearer 头无限制。客户端支持自定义请求头时，请始终使用请求头。
创建 Mind Key
[CODE BLOCK]
响应包含  — 请立即保存，它只显示一次。
列出你的 Mind
[CODE BLOCK]
删除 Mind（不可逆！）
[CODE BLOCK]
JWT（用于人类）
JWT 对用户账户进行认证，而非特定 Mind。用于：
- 账户注册与登录
- 创建/列出/删除 Mind
- 与其他用户共享 Mind
- Web Push 订阅管理
注册
[CODE BLOCK]
返回：
登录
[CODE BLOCK]
返回：
JWT 过期
JWT 在 7 天后过期。过期后再次调用  即可获取新 JWT。Mind Key 永不过期，因此现有 Agent 集成可继续工作。
安全最佳实践
> [!CRITICAL]
> - 绝不把 Mind Key 提交到 git。 使用环境变量。
> - 绝不在日志中记录 Mind Key。 在日志中遮蔽（）。
> - 怀疑泄露时轮换 key（删除 Mind、创建新 Mind）。
> - 每个项目用一个 Mind，以缩小 key 泄露的爆炸半径。
环境变量模式
[CODE BLOCK]
[CODE BLOCK]
MCP Server 配置
[CODE BLOCK]
多 Mind 模式
每个用户可有多个 Mind。常见模式：
| Mind 名称 | 用途 |
|-----------|---------|
|  | 工作相关记忆 |
|  | 个人偏好、家庭 |
|  | 特定项目上下文 |
|  | 学习进度 |
|  | 通用回退 |
在不同 LLM 会话中使用不同 Mind Key 即可隔离上下文。
限速
| 认证方式 | 限制 | 范围 |
|-------------|-------|-------|
| Mind Key（header） | 无 | 每个 Mind |
| Mind Key（?key=） | 60 次/分钟 | 每个 IP |
| JWT（header） | 无 | 每个用户 |
| 公共端点 | 无 | 全局 |
如适用，响应会包含限速头（、、）。
下一步
- Mind Key 与 JWT — 何时用哪个
- Memory API — 用 Mind Key 能做什么
- User API — 用 JWT 进行账户管理