认证与 Mind Key

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

两种认证方法

Mind Key（用于 Agent）

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

• 调用 API 的 LLM Agent
• 后台自动化脚本
• MCP Server 配置
• 任何长期集成

头部认证（推荐）

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

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

curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere

创建 Mind Key

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

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

列出你的 Mind

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

删除 Mind（不可逆！）

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

JWT（用于人类）

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

• 账户注册与登录
• 创建/列出/删除 Mind
• 与其他用户共享 Mind
• Web Push 订阅管理

注册

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

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

登录

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

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

JWT 过期

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

安全最佳实践

环境变量模式

# .env（绝不提交此文件）
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone

// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});

MCP Server 配置

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

多 Mind 模式

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

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

限速

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

下一步

• Mind Key 与 JWT — 何时用哪个
• Memory API — 用 Mind Key 能做什么
• User API — 用 JWT 进行账户管理