{"title":"인증 및 Mind Key","slug":"authentication","category":"getting-started","summary":"Synapse 인증 작동 방식: 에이전트용 Mind Key, 사람용 JWT, URL 전용 도구용 ?key=.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":435,"read_minutes":2,"llm_context":"Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).\nMind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)\nJWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)\nMind Key is shown only once at creation. Store it permanently.\nEach mind has exactly one Mind Key. Multiple minds = multiple keys.\n","lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 인증 및 Mind Key\n\nSynapse는 두 가지 인증 방법을 사용하며, 각각 다른 사용 사례에 최적화되어\n있습니다. 신뢰할 수 있는 통합을 구축하려면 차이를 이해하는 것이 필수적입니다.\n\n## 두 가지 인증 방법\n\n| 방법 | 사용 사례 | 속도 제한 | 만료 |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM 에이전트, 자동화 도구 | 없음 (헤더) / 분당 60회 (쿼리) | 없음 |\n| **JWT** | 사용자 대면 UI, 계정 작업 | 없음 | 7일 |\n\n## Mind Key (에이전트용)\n\nMind Key는 테넌트 범위의 API 토큰입니다. 단일 마인드의 데이터 (메모리, 작업,\n채팅, 스크립트 등)를 인증합니다. 다음에 사용하십시오:\n\n- API를 호출하는 LLM 에이전트\n- 백그라운드 자동화 스크립트\n- MCP 서버 구성\n- 모든 장기 통합\n\n### 헤더 인증 (권장)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### 쿼리 파라미터 (URL 전용 도구용)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> `?key=` 쿼리 파라미터는 **분당 60회**로 제한됩니다.\n> Bearer 헤더는 속도 제한이 없습니다. 클라이언트가 커스텀 헤더를 지원할\n> 때마다 헤더를 사용하십시오.\n\n### Mind Key 생성\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/minds \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Work Mind\", \"description\": \"Project memories\"}'\n```\n\n응답에 `mind_key`가 포함됩니다 — **즉시 저장하십시오**, 한 번만 표시됩니다.\n\n### 마인드 나열\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### 마인드 삭제 (되돌릴 수 없음!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (사람용)\n\nJWT는 특정 마인드가 아닌 **사용자 계정**을 인증합니다. 다음에 사용하십시오:\n\n- 계정 가입 및 로그인\n- 마인드 생성 / 나열 / 삭제\n- 다른 사용자와 마인드 공유\n- Web Push 구독 관리\n\n### 가입\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\n반환: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### 로그인\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\n반환: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### JWT 만료\n\nJWT는 **7일** 후에 만료됩니다. JWT가 만료되면 `/login`을 다시 호출하여\n새 것을 받으십시오. Mind Key는 만료되지 않으므로 기존 에이전트 통합은\n계속 작동합니다.\n\n## 보안 모범 사례\n\n> [!CRITICAL]\n> - **Mind Key를 git에 절대 커밋하지 마십시오.** 환경 변수를 사용하십시오.\n> - **Mind Key를 로그에 남기지 마십시오.** 로그에서 마스킹 (`mk_***...***xyz`).\n> - 유출이 의심되면 **키 교체** (마인드 삭제, 새로 생성).\n> - 키가 유출된 경우 피해 범위를 제한하기 위해 **프로젝트당 하나의 마인드 사용**.\n\n### 환경 변수 패턴\n\n```bash\n# .env (이 파일은 절대 커밋하지 마십시오)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone\n```\n\n```typescript\n// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n headers: { Authorization: `Bearer ${mindKey}` },\n});\n```\n\n### MCP 서버 구성\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_yourMindKeyHere\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n## 다중 마인드 패턴\n\n각 사용자는 여러 마인드를 가질 수 있습니다. 일반적인 패턴:\n\n| 마인드 이름 | 용도 |\n|-----------|---------|\n| `work` | 업무 관련 메모리 |\n| `personal` | 개인 선호도, 가족 |\n| `project-synapse` | 특정 프로젝트 컨텍스트 |\n| `learning-german` | 학습 진행 상황 |\n| `assistant-default` | 범용 폴백 |\n\n컨텍스트를 격리하기 위해 다른 LLM 세션에서 다른 Mind Key를 사용하십시오.\n\n## 속도 제한\n\n| 인증 방법 | 제한 | 범위 |\n|-------------|-------|-------|\n| Mind Key (헤더) | 없음 | 마인드별 |\n| Mind Key (?key=) | 분당 60회 | IP별 |\n| JWT (헤더) | 없음 | 사용자별 |\n| 공용 엔드포인트 | 없음 | 전역 |\n\n속도 제한 헤더 (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)는\n해당되는 경우 응답에 포함됩니다.\n\n## 다음 단계\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — 언제 무엇을 사용할지\n- [Memory API](/docs/api/memory) — Mind Key로 할 수 있는 것\n- [User API](/docs/api/user) — JWT로 계정 관리\n","content_html":"

인증 및 Mind Key

\n

Synapse는 두 가지 인증 방법을 사용하며, 각각 다른 사용 사례에 최적화되어\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 KeyLLM 에이전트, 자동화 도구없음 (헤더) / 분당 60회 (쿼리)없음
JWT사용자 대면 UI, 계정 작업없음7일
\n

Mind Key (에이전트용)

\n

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

\n\n

헤더 인증 (권장)

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

쿼리 파라미터 (URL 전용 도구용)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
`?key=` 쿼리 파라미터는 **분당 60회**로 제한됩니다.\nBearer 헤더는 속도 제한이 없습니다. 클라이언트가 커스텀 헤더를 지원할\n때마다 헤더를 사용하십시오.

Mind Key 생성

\n
curl -X POST https://synapse.schaefer.zone/minds \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"name": "Work Mind", "description": "Project memories"}'

응답에 mind_key가 포함됩니다 — 즉시 저장하십시오, 한 번만 표시됩니다.

\n

마인드 나열

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

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

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

JWT (사람용)

\n

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

\n\n

가입

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

반환: { "jwt": "eyJ...", "user": {...} }

\n

로그인

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

반환: { "jwt": "eyJ...", "user": {...} }

\n

JWT 만료

\n

JWT는 7일 후에 만료됩니다. JWT가 만료되면 /login을 다시 호출하여\n새 것을 받으십시오. Mind Key는 만료되지 않으므로 기존 에이전트 통합은\n계속 작동합니다.

\n

보안 모범 사례

\n

환경 변수 패턴

\n
# .env (이 파일은 절대 커밋하지 마십시오)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone
// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n  headers: { Authorization: `Bearer ${mindKey}` },\n});

MCP 서버 구성

\n
{\n  "mcpServers": {\n    "synapse": {\n      "command": "npx",\n      "args": ["-y", "synapse-mcp-api@latest"],\n      "env": {\n        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",\n        "SYNAPSE_URL": "https://synapse.schaefer.zone"\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
마인드 이름용도
work업무 관련 메모리
personal개인 선호도, 가족
project-synapse특정 프로젝트 컨텍스트
learning-german학습 진행 상황
assistant-default범용 폴백
\n

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

\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 (?key=)분당 60회IP별
JWT (헤더)없음사용자별
공용 엔드포인트없음전역
\n

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

\n

다음 단계

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