# Mind Key vs JWT — 언제 무엇을?

Synapse에는 두 가지 인증 토큰이 있습니다. 잘못 선택하면 401 오류가 발생합니다.
이 가이드는 명확한 결정 프레임워크를 제공합니다.

## 빠른 결정 표

| 하고 싶은 것 | 사용 |
|----------------|-----|
| 메모리 저장 / 회상 | Mind Key |
| 채팅 메시지 전송 / 폴링 | Mind Key |
| 작업 관리 | Mind Key |
| 스크립트 저장 | Mind Key |
| 웹훅 등록 | Mind Key |
| 컴퓨터 제어 | Mind Key (사용자 측) / Computer Token (에이전트 측) |
| 사용자 계정 가입 | 없음 (공용) |
| 로그인 | 없음 (공용) |
| 마인드 생성 / 나열 / 삭제 | JWT |
| 다른 사용자와 마인드 공유 | JWT |
| 웹 푸시 알림 구독 | JWT |
| 감사 로그 보기 | Mind Key |

## 단순한 규칙

> [!TIP]
> **단일 마인드의 데이터에 접근하면 → Mind Key.**
> **계정 또는 마인드 메타데이터를 관리하면 → JWT.**

## Mind Key — 데이터 접근 토큰

Mind Key는 **하나의 마인드 데이터**에 접근 권한을 부여합니다. 만료되지 않는
(마인드가 삭제될 때까지) 장기 토큰입니다. 다음에 적합:

- 세션 간 메모리를 유지하는 LLM 에이전트
- 백그라운드 cron 작업
- MCP 서버 구성
- 웹훅 통합
- 메모리를 읽는 모바일 앱

### Mind Key가 할 수 있는 것

- `GET /memory/recall` — 이 마인드의 모든 메모리 읽기
- `POST /memory` — 메모리 저장/업데이트
- `GET /chat/poll` — 채팅 메시지 읽기
- `POST /chat/reply` — 채팅 메시지 전송
- `GET /mind/tasks` — 작업 나열
- `POST /mind/task` — 작업 생성
- `POST /script` — 스크립트 저장
- `POST /webhooks` — 웹훅 등록
- `POST /computers/:id/commands` — 컴퓨터 명령 큐잉

### Mind Key가 할 수 없는 것

- 마인드 생성 / 나열 / 삭제 (JWT 필요)
- 다른 사용자와 마인드 공유 (JWT 필요)
- 사용자 계정 정보 보기 (JWT 필요)
- 웹 푸시 구독 (JWT 필요)

## JWT — 계정 관리 토큰

JWT는 **사용자 계정**을 인증합니다. 7일 후에 만료되며 여러 마인드에 걸치거나
다른 사용자와 관련된 계정 수준 작업에 사용됩니다.

### JWT가 할 수 있는 것

- `POST /minds` — 새 마인드 생성 (새 Mind Key 반환)
- `GET /minds` — 이 사용자의 모든 마인드 나열
- `DELETE /minds/:id` — 마인드 삭제
- `POST /sharing` — 다른 사용자와 마인드 공유
- `POST /push/subscribe` — 웹 푸시 알림 구독
- `GET /sharing` — 마인드 공유 나열

### JWT가 할 수 없는 것

- 메모리 읽기 / 쓰기 (Mind Key 필요)
- 채팅 메시지 전송 (Mind Key 필요)
- 작업 관리 (Mind Key 필요)
- 웹훅 등록 (Mind Key 필요)

## 특수 사례: Computer Token

`/computers/me/*` 엔드포인트 (에이전트 측, screen-remote-agent용)는 세 번째
토큰 유형인 **Computer Token**을 사용합니다. 이 토큰은 설치 코드를 상환할
때 `POST /computers/register`에 의해 반환되며, 하나의 등록된 컴퓨터에
특정합니다.

| 엔드포인트 | 인증 |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key 또는 JWT |
| `POST /computers/:id/commands` | Mind Key 또는 JWT |

## 일반적인 패턴

### 패턴 1: 단일 LLM 에이전트

1. 한 번 가입 → JWT 획득
2. 하나의 마인드 생성 → Mind Key 획득
3. LLM이 모든 것에 Mind Key 사용

### 패턴 2: 다중 프로젝트 에이전트

1. 한 번 가입 → JWT 획득
2. 여러 마인드 생성 (work, personal, project-x) → 여러 Mind Key 획득
3. LLM이 컨텍스트에 따라 다른 Mind Key 로드

### 패턴 3: 팀 공유

1. 사용자 A가 마인드 생성 → Mind Key A 획득
2. 사용자 A가 JWT로 사용자 B와 공유 (`POST /sharing`)
3. 사용자 B는 이제 자신의 JWT로 접근 가능
4. LLM 접근을 위해 사용자 B는 자체 Mind Key 생성 필요 (또는 A의 것 사용)

### 패턴 4: MCP 서버

MCP 서버는 항상 Mind Key 사용 (`SYNAPSE_MIND_KEY` 환경 변수로 설정). 하나의
MCP 서버 인스턴스 = 하나의 마인드. 다중 마인드 접근을 위해 여러 MCP
인스턴스를 실행하거나 클라이언트 측 마인드 전환을 구현하십시오.

## 토큰 형식 치트 시트

| 토큰 | 형식 | 예시 |
|-------|--------|---------|
| Mind Key | `mk_` + 36자 | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36자 | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## 다음 단계

- [Authentication](/docs/getting-started/authentication) — 전체 인증 가이드
- [User 및 Minds API](/docs/api/user) — JWT로 보호된 엔드포인트
- [Memory API](/docs/api/memory) — Mind Key로 보호된 엔드포인트