# 인증 및 Mind Key

Synapse는 두 가지 인증 방법을 사용하며, 각각 다른 사용 사례에 최적화되어
있습니다. 신뢰할 수 있는 통합을 구축하려면 차이를 이해하는 것이 필수적입니다.

## 두 가지 인증 방법

| 방법 | 사용 사례 | 속도 제한 | 만료 |
|--------|----------|------------|--------|
| **Mind Key** | LLM 에이전트, 자동화 도구 | 없음 (헤더) / 분당 60회 (쿼리) | 없음 |
| **JWT** | 사용자 대면 UI, 계정 작업 | 없음 | 7일 |

## Mind Key (에이전트용)

Mind Key는 테넌트 범위의 API 토큰입니다. 단일 마인드의 데이터 (메모리, 작업,
채팅, 스크립트 등)를 인증합니다. 다음에 사용하십시오:

- API를 호출하는 LLM 에이전트
- 백그라운드 자동화 스크립트
- MCP 서버 구성
- 모든 장기 통합

### 헤더 인증 (권장)

```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`가 포함됩니다 — **즉시 저장하십시오**, 한 번만 표시됩니다.

### 마인드 나열

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

### 마인드 삭제 (되돌릴 수 없음!)

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

## JWT (사람용)

JWT는 특정 마인드가 아닌 **사용자 계정**을 인증합니다. 다음에 사용하십시오:

- 계정 가입 및 로그인
- 마인드 생성 / 나열 / 삭제
- 다른 사용자와 마인드 공유
- 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일** 후에 만료됩니다. JWT가 만료되면 `/login`을 다시 호출하여
새 것을 받으십시오. Mind Key는 만료되지 않으므로 기존 에이전트 통합은
계속 작동합니다.

## 보안 모범 사례

> [!CRITICAL]
> - **Mind Key를 git에 절대 커밋하지 마십시오.** 환경 변수를 사용하십시오.
> - **Mind Key를 로그에 남기지 마십시오.** 로그에서 마스킹 (`mk_***...***xyz`).
> - 유출이 의심되면 **키 교체** (마인드 삭제, 새로 생성).
> - 키가 유출된 경우 피해 범위를 제한하기 위해 **프로젝트당 하나의 마인드 사용**.

### 환경 변수 패턴

```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 서버 구성

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

## 다중 마인드 패턴

각 사용자는 여러 마인드를 가질 수 있습니다. 일반적인 패턴:

| 마인드 이름 | 용도 |
|-----------|---------|
| `work` | 업무 관련 메모리 |
| `personal` | 개인 선호도, 가족 |
| `project-synapse` | 특정 프로젝트 컨텍스트 |
| `learning-german` | 학습 진행 상황 |
| `assistant-default` | 범용 폴백 |

컨텍스트를 격리하기 위해 다른 LLM 세션에서 다른 Mind Key를 사용하십시오.

## 속도 제한

| 인증 방법 | 제한 | 범위 |
|-------------|-------|-------|
| Mind Key (헤더) | 없음 | 마인드별 |
| Mind Key (?key=) | 분당 60회 | IP별 |
| JWT (헤더) | 없음 | 사용자별 |
| 공용 엔드포인트 | 없음 | 전역 |

속도 제한 헤더 (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)는
해당되는 경우 응답에 포함됩니다.

## 다음 단계

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — 언제 무엇을 사용할지
- [Memory API](/docs/api/memory) — Mind Key로 할 수 있는 것
- [User API](/docs/api/user) — JWT로 계정 관리