# 认证与 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 配置
- 任何长期集成

### 头部认证（推荐）

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

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

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

> [!WARNING]
> `?key=` 查询参数被限速为**每分钟 60 次请求**。Bearer 头无限制。客户端支持自定义请求头时，请始终使用请求头。

### 创建 Mind Key

```bash
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

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

### 删除 Mind（不可逆！）

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

## JWT（用于人类）

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

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

### 注册

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

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

### 登录

```bash
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 集成可继续工作。

## 安全最佳实践

> [!CRITICAL]
> - **绝不把 Mind Key 提交到 git。** 使用环境变量。
> - **绝不在日志中记录 Mind Key。** 在日志中遮蔽（`mk_***...***xyz`）。
> - **怀疑泄露时轮换 key**（删除 Mind、创建新 Mind）。
> - **每个项目用一个 Mind**，以缩小 key 泄露的爆炸半径。

### 环境变量模式

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

```typescript
// 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 配置

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

## 多 Mind 模式

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

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

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

## 限速

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

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

## 下一步

- [Mind Key 与 JWT](/docs/getting-started/mind-key-vs-jwt) — 何时用哪个
- [Memory API](/docs/api/memory) — 用 Mind Key 能做什么
- [User API](/docs/api/user) — 用 JWT 进行账户管理