# Authentication & Mind Key

Synapse ใช้สองวิธี authentication แต่ละวิธีปรับให้เหมาะกับกรณีใช้งานต่างกัน การเข้าใจความแตกต่างเป็นสิ่งจำเป็นสำหรับการสร้าง integration ที่เชื่อถือได้

## สองวิธี Auth

| วิธี | กรณีใช้งาน | Rate Limit | Expiry |
|--------|----------|------------|--------|
| **Mind Key** | LLM agent, เครื่องมืออัตโนมัติ | None (header) / 60 ต่อนาที (query) | ไม่มี |
| **JWT** | Human-facing UI, การดำเนินการบัญชี | None | 7 วัน |

## Mind Key (สำหรับ Agent)

Mind Key เป็น tenant-scoped API token ใช้ยืนยันตัวตนข้อมูล mind เดียว (memory, task, chat, script ฯลฯ) ใช้สำหรับ:

- LLM agent เรียก API
- สคริปต์ automation เบื้องหลัง
- การกำหนดค่า MCP server
- integration ที่อยู่ยาวนานใด ๆ

### Header authentication (แนะนำ)

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

### Query parameter (สำหรับเครื่องมือ URL-only)

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

> [!WARNING]
> `?key=` query parameter จำกัดที่ **60 request ต่อนาที** Bearer header ไม่จำกัด ใช้ header เมื่อใดก็ตามที่ client ของคุณรองรับ custom header

### การสร้าง 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"}'
```

Response รวม `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 (สำหรับ Human)

JWT ยืนยันตัวตน **บัญชีผู้ใช้** ไม่ใช่ mind เฉพาะ ใช้สำหรับ:

- การสมัครและล็อกอินบัญชี
- สร้าง / รายการ / ลบ mind
- แชร์ mind กับผู้ใช้อื่น
- การจัดการ Web Push subscription

### สมัคร

```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 วัน** เมื่อ JWT หมดอายุ เพียงเรียก `/login` อีกครั้งเพื่อรับใหม่ Mind Key ไม่หมดอายุ ดังนั้น integration ของ agent ที่มีอยู่ยังทำงานต่อ

## แนวทางปฏิบัติด้านความปลอดภัย

> [!CRITICAL]
> - **อย่า commit Mind Key ลง git** ใช้ environment variable
> - **อย่า log Mind Key** ปิดบังใน log (`mk_***...***xyz`)
> - **หมุนเวียน key** หากคุณสงสัยว่ารั่ว (ลบ mind, สร้างใหม่)
> - **ใช้หนึ่ง mind ต่อโปรเจกต์** เพื่อจำกัดผลกระทบหาก key รั่ว

### รูปแบบ environment variable

```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}` },
});
```

### กำหนดค่า 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"
      }
    }
  }
}
```

## รูปแบบ Multi-Mind

ผู้ใช้แต่ละคนสามารถมีหลาย mind รูปแบบทั่วไป:

| ชื่อ Mind | วัตถุประสงค์ |
|-----------|---------|
| `work` | memory เกี่ยวกับงาน |
| `personal` | ค่ากำหนดส่วนตัว, ครอบครัว |
| `project-synapse` | context โปรเจกต์เฉพาะ |
| `learning-german` | ความคืบหน้าการเรียนรู้ |
| `assistant-default` | fallback สำหรับใช้ทั่วไป |

ใช้ Mind Key ต่างกันสำหรับ LLM session ต่างกันเพื่อแยก context

## Rate Limit

| วิธี Auth | Limit | Scope |
|-------------|-------|-------|
| Mind Key (header) | None | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | None | Per-user |
| Public endpoint | None | Global |

Rate limit header (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`) รวมอยู่ใน response เมื่อเกี่ยวข้อง

## ขั้นตอนถัดไป

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — เมื่อใช้อันไหน
- [Memory API](/docs/api/memory) — สิ่งที่คุณทำได้กับ Mind Key
- [User API](/docs/api/user) — การจัดการบัญชีด้วย JWT