# Xác thực & Mind Key

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

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

| Phương thức | Trường hợp | Giới hạn tốc độ | Hết hạn |
|--------|----------|------------|--------|
| **Mind Key** | LLM agent, công cụ tự động | 120/phút (Bearer ngoài); ?key= tắt theo mặc định (deny) | Không bao giờ |
| **JWT** | Giao diện hướng con người, thao tác tài khoản | 120/phút (IP bên ngoài) | 7 ngày |

## Mind Key (cho Agent)

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

- LLM agent gọi API
- Script tự động hóa nền
- Cấu hình MCP server
- Bất kỳ tích hợp tồn tại lâu dài nào

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

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

### Tham số query (tắt theo mặc định)

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

> [!WARNING]
> Tham số query `?key=` được **tắt** bởi mặc định đã siết `AUTH_QUERY_KEY_MODE=deny`: máy chủ trả về
> `?key=` với 401 kèm gợi ý "Query-param auth (?key=) is disabled". Chỉ Bearer là mặc định an toàn (SSOT: `src/lib/auth.ts`).
> Chỉ khi một nhà vận hành đặt rõ ràng `AUTH_QUERY_KEY_MODE=allow`, `?key=` mới hoạt động như van
> chuyển tiếp với 60 req/min (mỗi IP). Client Bearer bên ngoài nhận 120 req/min theo danh tính;
> mạng nội bộ đáng tin cậy không giới hạn. Sử dụng header bất cứ khi nào client của bạn hỗ trợ header tùy chỉnh.

### Tạo 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"}'
```

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.

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

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

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

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

## JWT (cho Con người)

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:

- Đăng ký và đăng nhập tài khoản
- Tạo / liệt kê / xóa mind
- Chia sẻ mind với người dùng khác
- Quản lý đăng ký Web Push

### Đăng ký

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

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

### Đăng nhập

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

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

### Hết hạn JWT

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
JWT 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
tục hoạt động.

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

> [!CRITICAL]
> - **Không bao giờ commit Mind Key vào git.** Sử dụng biến môi trường.
> - **Không bao giờ ghi nhật ký Mind Key.** Che chúng trong nhật ký (`mk_***...***xyz`).
> - **Xoay vòng key** nếu bạn nghi ngờ lộ lọt (xóa mind, tạo mới).
> - **Sử dụng một mind mỗi dự án** để giới hạn thiệt hại nếu key bị lộ.

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

```bash
# .env (NEVER commit this file)
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}` },
});
```

### Cấu hình 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"
      }
    }
  }
}
```

## Mẫu Multi-Mind

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

| Tên Mind | Mục đích |
|-----------|---------|
| `work` | Bộ nhớ liên quan công việc |
| `personal` | Sở thích cá nhân, gia đình |
| `project-synapse` | Ngữ cảnh dự án cụ thể |
| `learning-german` | Tiến độ học tập |
| `assistant-default` | Fallback mục đích chung |

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
biệt.

## Giới hạn tốc độ

| Phương thức xác thực | Giới hạn | Phạm vi |
|-------------|-------|-------|
| Mind Key (header) | 120/phút từ IP bên ngoài (mỗi định danh); không giới hạn cho mạng nội bộ đáng tin cậy | Mỗi mind |
| Mind Key (?key=, chỉ khi allow) | 60/phút | Mỗi IP |
| JWT (header) | 120 yêu cầu/phút (IP bên ngoài; không giới hạn cho mạng nội bộ đáng tin cậy) | Mỗi người dùng |
| Endpoint công khai | Không | Toàn cầu |

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

## Bước tiếp theo

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — khi nào dùng cái nào
- [Memory API](/docs/api/memory) — những gì bạn có thể làm với Mind Key
- [User API](/docs/api/user) — quản lý tài khoản với JWT