{"title":"Mind Key vs JWT — 언제 무엇을?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"결정 가이드: 에이전트 데이터 접근용 Mind Key, 계정 관리용 JWT.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":640,"read_minutes":3,"llm_context":"Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.\nJWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.\nSimple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.\nException: /computers/me/* uses Computer Token (not Mind Key or JWT).\n","lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# Mind Key vs JWT — 언제 무엇을?\n\nSynapse에는 두 가지 인증 토큰이 있습니다. 잘못 선택하면 401 오류가 발생합니다.\n이 가이드는 명확한 결정 프레임워크를 제공합니다.\n\n## 빠른 결정 표\n\n| 하고 싶은 것 | 사용 |\n|----------------|-----|\n| 메모리 저장 / 회상 | Mind Key |\n| 채팅 메시지 전송 / 폴링 | Mind Key |\n| 작업 관리 | Mind Key |\n| 스크립트 저장 | Mind Key |\n| 웹훅 등록 | Mind Key |\n| 컴퓨터 제어 | Mind Key (사용자 측) / Computer Token (에이전트 측) |\n| 사용자 계정 가입 | 없음 (공용) |\n| 로그인 | 없음 (공용) |\n| 마인드 생성 / 나열 / 삭제 | JWT |\n| 다른 사용자와 마인드 공유 | JWT |\n| 웹 푸시 알림 구독 | JWT |\n| 감사 로그 보기 | Mind Key |\n\n## 단순한 규칙\n\n> [!TIP]\n> **단일 마인드의 데이터에 접근하면 → Mind Key.**\n> **계정 또는 마인드 메타데이터를 관리하면 → JWT.**\n\n## Mind Key — 데이터 접근 토큰\n\nMind Key는 **하나의 마인드 데이터**에 접근 권한을 부여합니다. 만료되지 않는\n(마인드가 삭제될 때까지) 장기 토큰입니다. 다음에 적합:\n\n- 세션 간 메모리를 유지하는 LLM 에이전트\n- 백그라운드 cron 작업\n- MCP 서버 구성\n- 웹훅 통합\n- 메모리를 읽는 모바일 앱\n\n### Mind Key가 할 수 있는 것\n\n- `GET /memory/recall` — 이 마인드의 모든 메모리 읽기\n- `POST /memory` — 메모리 저장/업데이트\n- `GET /chat/poll` — 채팅 메시지 읽기\n- `POST /chat/reply` — 채팅 메시지 전송\n- `GET /mind/tasks` — 작업 나열\n- `POST /mind/task` — 작업 생성\n- `POST /script` — 스크립트 저장\n- `POST /webhooks` — 웹훅 등록\n- `POST /computers/:id/commands` — 컴퓨터 명령 큐잉\n\n### Mind Key가 할 수 없는 것\n\n- 마인드 생성 / 나열 / 삭제 (JWT 필요)\n- 다른 사용자와 마인드 공유 (JWT 필요)\n- 사용자 계정 정보 보기 (JWT 필요)\n- 웹 푸시 구독 (JWT 필요)\n\n## JWT — 계정 관리 토큰\n\nJWT는 **사용자 계정**을 인증합니다. 7일 후에 만료되며 여러 마인드에 걸치거나\n다른 사용자와 관련된 계정 수준 작업에 사용됩니다.\n\n### JWT가 할 수 있는 것\n\n- `POST /minds` — 새 마인드 생성 (새 Mind Key 반환)\n- `GET /minds` — 이 사용자의 모든 마인드 나열\n- `DELETE /minds/:id` — 마인드 삭제\n- `POST /sharing` — 다른 사용자와 마인드 공유\n- `POST /push/subscribe` — 웹 푸시 알림 구독\n- `GET /sharing` — 마인드 공유 나열\n\n### JWT가 할 수 없는 것\n\n- 메모리 읽기 / 쓰기 (Mind Key 필요)\n- 채팅 메시지 전송 (Mind Key 필요)\n- 작업 관리 (Mind Key 필요)\n- 웹훅 등록 (Mind Key 필요)\n\n## 특수 사례: Computer Token\n\n`/computers/me/*` 엔드포인트 (에이전트 측, screen-remote-agent용)는 세 번째\n토큰 유형인 **Computer Token**을 사용합니다. 이 토큰은 설치 코드를 상환할\n때 `POST /computers/register`에 의해 반환되며, 하나의 등록된 컴퓨터에\n특정합니다.\n\n| 엔드포인트 | 인증 |\n|----------|------|\n| `GET /computers/me/poll` | Computer Token |\n| `POST /computers/me/commands/:cid/result` | Computer Token |\n| `GET /computers/list` | Mind Key 또는 JWT |\n| `POST /computers/:id/commands` | Mind Key 또는 JWT |\n\n## 일반적인 패턴\n\n### 패턴 1: 단일 LLM 에이전트\n\n1. 한 번 가입 → JWT 획득\n2. 하나의 마인드 생성 → Mind Key 획득\n3. LLM이 모든 것에 Mind Key 사용\n\n### 패턴 2: 다중 프로젝트 에이전트\n\n1. 한 번 가입 → JWT 획득\n2. 여러 마인드 생성 (work, personal, project-x) → 여러 Mind Key 획득\n3. LLM이 컨텍스트에 따라 다른 Mind Key 로드\n\n### 패턴 3: 팀 공유\n\n1. 사용자 A가 마인드 생성 → Mind Key A 획득\n2. 사용자 A가 JWT로 사용자 B와 공유 (`POST /sharing`)\n3. 사용자 B는 이제 자신의 JWT로 접근 가능\n4. LLM 접근을 위해 사용자 B는 자체 Mind Key 생성 필요 (또는 A의 것 사용)\n\n### 패턴 4: MCP 서버\n\nMCP 서버는 항상 Mind Key 사용 (`SYNAPSE_MIND_KEY` 환경 변수로 설정). 하나의\nMCP 서버 인스턴스 = 하나의 마인드. 다중 마인드 접근을 위해 여러 MCP\n인스턴스를 실행하거나 클라이언트 측 마인드 전환을 구현하십시오.\n\n## 토큰 형식 치트 시트\n\n| 토큰 | 형식 | 예시 |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36자 | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36자 | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## 다음 단계\n\n- [Authentication](/docs/getting-started/authentication) — 전체 인증 가이드\n- [User 및 Minds API](/docs/api/user) — JWT로 보호된 엔드포인트\n- [Memory API](/docs/api/memory) — Mind Key로 보호된 엔드포인트\n","content_html":"

Mind Key vs JWT — 언제 무엇을?

\n

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

\n

빠른 결정 표

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

단순한 규칙

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

Mind Key — 데이터 접근 토큰

\n

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

\n\n

Mind Key가 할 수 있는 것

\n\n

Mind Key가 할 수 없는 것

\n\n

JWT — 계정 관리 토큰

\n

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

\n

JWT가 할 수 있는 것

\n\n

JWT가 할 수 없는 것

\n\n

특수 사례: Computer Token

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
엔드포인트인증
GET /computers/me/pollComputer Token
POST /computers/me/commands/:cid/resultComputer Token
GET /computers/listMind Key 또는 JWT
POST /computers/:id/commandsMind Key 또는 JWT
\n

일반적인 패턴

\n

패턴 1: 단일 LLM 에이전트

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

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

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

패턴 3: 팀 공유

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

패턴 4: MCP 서버

\n

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

\n

토큰 형식 치트 시트

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
토큰형식예시
Mind Keymk_ + 36자mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789
JWTeyJ + base64eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Computer Tokenct_ + 36자ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789
\n

다음 단계

\n\n","urls":{"html":"/docs/getting-started/mind-key-vs-jwt","text":"/docs/getting-started/mind-key-vs-jwt?format=text","json":"/docs/getting-started/mind-key-vs-jwt?format=json","llm":"/docs/getting-started/mind-key-vs-jwt?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}