{"title":"Authentication & Mind Key","slug":"authentication","category":"getting-started","summary":"วิธีที่ Synapse authentication ทำงาน: Mind Key สำหรับ agent, JWT สำหรับ human, ?key= สำหรับเครื่องมือ URL-only","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":364,"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":"th","translated":true,"requested_lang":"th","content_markdown":"\n# Authentication & Mind Key\n\nSynapse ใช้สองวิธี authentication แต่ละวิธีปรับให้เหมาะกับกรณีใช้งานต่างกัน การเข้าใจความแตกต่างเป็นสิ่งจำเป็นสำหรับการสร้าง integration ที่เชื่อถือได้\n\n## สองวิธี Auth\n\n| วิธี | กรณีใช้งาน | Rate Limit | Expiry |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM agent, เครื่องมืออัตโนมัติ | None (header) / 60 ต่อนาที (query) | ไม่มี |\n| **JWT** | Human-facing UI, การดำเนินการบัญชี | None | 7 วัน |\n\n## Mind Key (สำหรับ Agent)\n\nMind Key เป็น tenant-scoped API token ใช้ยืนยันตัวตนข้อมูล mind เดียว (memory, task, chat, script ฯลฯ) ใช้สำหรับ:\n\n- LLM agent เรียก API\n- สคริปต์ automation เบื้องหลัง\n- การกำหนดค่า MCP server\n- integration ที่อยู่ยาวนานใด ๆ\n\n### Header authentication (แนะนำ)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n     https://synapse.schaefer.zone/memory/recall\n```\n\n### Query parameter (สำหรับเครื่องมือ URL-only)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> `?key=` query parameter จำกัดที่ **60 request ต่อนาที** Bearer header ไม่จำกัด ใช้ header เมื่อใดก็ตามที่ client ของคุณรองรับ custom header\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\nResponse รวม `mind_key` — **บันทึกทันที** แสดงเพียงครั้งเดียว\n\n### รายการ mind ของคุณ\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n     https://synapse.schaefer.zone/minds\n```\n\n### ลบ mind (ย้อนกลับไม่ได้!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n     https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (สำหรับ Human)\n\nJWT ยืนยันตัวตน **บัญชีผู้ใช้** ไม่ใช่ mind เฉพาะ ใช้สำหรับ:\n\n- การสมัครและล็อกอินบัญชี\n- สร้าง / รายการ / ลบ mind\n- แชร์ mind กับผู้ใช้อื่น\n- การจัดการ Web Push subscription\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` อีกครั้งเพื่อรับใหม่ Mind Key ไม่หมดอายุ ดังนั้น integration ของ agent ที่มีอยู่ยังทำงานต่อ\n\n## แนวทางปฏิบัติด้านความปลอดภัย\n\n> [!CRITICAL]\n> - **อย่า commit Mind Key ลง git** ใช้ environment variable\n> - **อย่า log Mind Key** ปิดบังใน log (`mk_***...***xyz`)\n> - **หมุนเวียน key** หากคุณสงสัยว่ารั่ว (ลบ mind, สร้างใหม่)\n> - **ใช้หนึ่ง mind ต่อโปรเจกต์** เพื่อจำกัดผลกระทบหาก key รั่ว\n\n### รูปแบบ environment variable\n\n```bash\n# .env (NEVER commit this file)\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 server\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## รูปแบบ Multi-Mind\n\nผู้ใช้แต่ละคนสามารถมีหลาย mind รูปแบบทั่วไป:\n\n| ชื่อ Mind | วัตถุประสงค์ |\n|-----------|---------|\n| `work` | memory เกี่ยวกับงาน |\n| `personal` | ค่ากำหนดส่วนตัว, ครอบครัว |\n| `project-synapse` | context โปรเจกต์เฉพาะ |\n| `learning-german` | ความคืบหน้าการเรียนรู้ |\n| `assistant-default` | fallback สำหรับใช้ทั่วไป |\n\nใช้ Mind Key ต่างกันสำหรับ LLM session ต่างกันเพื่อแยก context\n\n## Rate Limit\n\n| วิธี Auth | Limit | Scope |\n|-------------|-------|-------|\n| Mind Key (header) | None | Per-mind |\n| Mind Key (?key=) | 60/min | Per-IP |\n| JWT (header) | None | Per-user |\n| Public endpoint | None | Global |\n\nRate limit header (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`) รวมอยู่ใน response เมื่อเกี่ยวข้อง\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":"<h1>Authentication &amp; Mind Key</h1>\n<p>Synapse ใช้สองวิธี authentication แต่ละวิธีปรับให้เหมาะกับกรณีใช้งานต่างกัน การเข้าใจความแตกต่างเป็นสิ่งจำเป็นสำหรับการสร้าง integration ที่เชื่อถือได้</p>\n<h2>สองวิธี Auth</h2>\n<table>\n<thead>\n<tr>\n<th>วิธี</th>\n<th>กรณีใช้งาน</th>\n<th>Rate Limit</th>\n<th>Expiry</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><strong>Mind Key</strong></td>\n<td>LLM agent, เครื่องมืออัตโนมัติ</td>\n<td>None (header) / 60 ต่อนาที (query)</td>\n<td>ไม่มี</td>\n</tr>\n<tr>\n<td><strong>JWT</strong></td>\n<td>Human-facing UI, การดำเนินการบัญชี</td>\n<td>None</td>\n<td>7 วัน</td>\n</tr>\n</tbody></table>\n<h2>Mind Key (สำหรับ Agent)</h2>\n<p>Mind Key เป็น tenant-scoped API token ใช้ยืนยันตัวตนข้อมูล mind เดียว (memory, task, chat, script ฯลฯ) ใช้สำหรับ:</p>\n<ul>\n<li>LLM agent เรียก API</li>\n<li>สคริปต์ automation เบื้องหลัง</li>\n<li>การกำหนดค่า MCP server</li>\n<li>integration ที่อยู่ยาวนานใด ๆ</li>\n</ul>\n<h3>Header authentication (แนะนำ)</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer mk_yourMindKeyHere&quot;</span> \\\n     https://synapse.schaefer.zone/memory/recall</code></pre><h3>Query parameter (สำหรับเครื่องมือ URL-only)</h3>\n<pre><code class=\"hljs language-bash\">curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere</code></pre><div class=\"callout callout-warn\">`?key=` query parameter จำกัดที่ **60 request ต่อนาที** Bearer header ไม่จำกัด ใช้ header เมื่อใดก็ตามที่ client ของคุณรองรับ custom header</div><h3>การสร้าง Mind Key</h3>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/minds \\\n  -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;name&quot;: &quot;Work Mind&quot;, &quot;description&quot;: &quot;Project memories&quot;}&#x27;</span></code></pre><p>Response รวม <code>mind_key</code> — <strong>บันทึกทันที</strong> แสดงเพียงครั้งเดียว</p>\n<h3>รายการ mind ของคุณ</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n     https://synapse.schaefer.zone/minds</code></pre><h3>ลบ mind (ย้อนกลับไม่ได้!)</h3>\n<pre><code class=\"hljs language-bash\">curl -X DELETE -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n     https://synapse.schaefer.zone/minds/m_xyz789</code></pre><h2>JWT (สำหรับ Human)</h2>\n<p>JWT ยืนยันตัวตน <strong>บัญชีผู้ใช้</strong> ไม่ใช่ mind เฉพาะ ใช้สำหรับ:</p>\n<ul>\n<li>การสมัครและล็อกอินบัญชี</li>\n<li>สร้าง / รายการ / ลบ mind</li>\n<li>แชร์ mind กับผู้ใช้อื่น</li>\n<li>การจัดการ Web Push subscription</li>\n</ul>\n<h3>สมัคร</h3>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/register \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;email&quot;: &quot;you@example.com&quot;, &quot;password&quot;: &quot;secret&quot;}&#x27;</span></code></pre><p>ส่งกลับ: <code>{ &quot;jwt&quot;: &quot;eyJ...&quot;, &quot;user&quot;: {...} }</code></p>\n<h3>ล็อกอิน</h3>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/login \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;email&quot;: &quot;you@example.com&quot;, &quot;password&quot;: &quot;secret&quot;}&#x27;</span></code></pre><p>ส่งกลับ: <code>{ &quot;jwt&quot;: &quot;eyJ...&quot;, &quot;user&quot;: {...} }</code></p>\n<h3>การหมดอายุของ JWT</h3>\n<p>JWT หมดอายุหลัง <strong>7 วัน</strong> เมื่อ JWT หมดอายุ เพียงเรียก <code>/login</code> อีกครั้งเพื่อรับใหม่ Mind Key ไม่หมดอายุ ดังนั้น integration ของ agent ที่มีอยู่ยังทำงานต่อ</p>\n<h2>แนวทางปฏิบัติด้านความปลอดภัย</h2>\n<div class=\"callout callout-critical\"></div><h3>รูปแบบ environment variable</h3>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># .env (NEVER commit this file)</span>\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone</code></pre><pre><code class=\"hljs language-typescript\"><span class=\"hljs-comment\">// Node.js</span>\n<span class=\"hljs-keyword\">const</span> mindKey = process.<span class=\"hljs-property\">env</span>.<span class=\"hljs-property\">SYNAPSE_MIND_KEY</span>;\n<span class=\"hljs-keyword\">const</span> url = process.<span class=\"hljs-property\">env</span>.<span class=\"hljs-property\">SYNAPSE_URL</span>;\n<span class=\"hljs-keyword\">await</span> <span class=\"hljs-title function_\">fetch</span>(<span class=\"hljs-string\">`<span class=\"hljs-subst\">${url}</span>/memory/recall`</span>, {\n  <span class=\"hljs-attr\">headers</span>: { <span class=\"hljs-title class_\">Authorization</span>: <span class=\"hljs-string\">`Bearer <span class=\"hljs-subst\">${mindKey}</span>`</span> },\n});</code></pre><h3>กำหนดค่า MCP server</h3>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span>\n  <span class=\"hljs-attr\">&quot;mcpServers&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">{</span>\n    <span class=\"hljs-attr\">&quot;synapse&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">{</span>\n      <span class=\"hljs-attr\">&quot;command&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;npx&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;args&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">[</span><span class=\"hljs-string\">&quot;-y&quot;</span><span class=\"hljs-punctuation\">,</span> <span class=\"hljs-string\">&quot;synapse-mcp-api@latest&quot;</span><span class=\"hljs-punctuation\">]</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;env&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">{</span>\n        <span class=\"hljs-attr\">&quot;SYNAPSE_MIND_KEY&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;mk_yourMindKeyHere&quot;</span><span class=\"hljs-punctuation\">,</span>\n        <span class=\"hljs-attr\">&quot;SYNAPSE_URL&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone&quot;</span>\n      <span class=\"hljs-punctuation\">}</span>\n    <span class=\"hljs-punctuation\">}</span>\n  <span class=\"hljs-punctuation\">}</span>\n<span class=\"hljs-punctuation\">}</span></code></pre><h2>รูปแบบ Multi-Mind</h2>\n<p>ผู้ใช้แต่ละคนสามารถมีหลาย mind รูปแบบทั่วไป:</p>\n<table>\n<thead>\n<tr>\n<th>ชื่อ Mind</th>\n<th>วัตถุประสงค์</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>work</code></td>\n<td>memory เกี่ยวกับงาน</td>\n</tr>\n<tr>\n<td><code>personal</code></td>\n<td>ค่ากำหนดส่วนตัว, ครอบครัว</td>\n</tr>\n<tr>\n<td><code>project-synapse</code></td>\n<td>context โปรเจกต์เฉพาะ</td>\n</tr>\n<tr>\n<td><code>learning-german</code></td>\n<td>ความคืบหน้าการเรียนรู้</td>\n</tr>\n<tr>\n<td><code>assistant-default</code></td>\n<td>fallback สำหรับใช้ทั่วไป</td>\n</tr>\n</tbody></table>\n<p>ใช้ Mind Key ต่างกันสำหรับ LLM session ต่างกันเพื่อแยก context</p>\n<h2>Rate Limit</h2>\n<table>\n<thead>\n<tr>\n<th>วิธี Auth</th>\n<th>Limit</th>\n<th>Scope</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key (header)</td>\n<td>None</td>\n<td>Per-mind</td>\n</tr>\n<tr>\n<td>Mind Key (?key=)</td>\n<td>60/min</td>\n<td>Per-IP</td>\n</tr>\n<tr>\n<td>JWT (header)</td>\n<td>None</td>\n<td>Per-user</td>\n</tr>\n<tr>\n<td>Public endpoint</td>\n<td>None</td>\n<td>Global</td>\n</tr>\n</tbody></table>\n<p>Rate limit header (<code>X-RateLimit-Limit</code>, <code>X-RateLimit-Remaining</code>, <code>Retry-After</code>) รวมอยู่ใน response เมื่อเกี่ยวข้อง</p>\n<h2>ขั้นตอนถัดไป</h2>\n<ul>\n<li><a href=\"/docs/getting-started/mind-key-vs-jwt\">Mind Key vs JWT</a> — เมื่อใช้อันไหน</li>\n<li><a href=\"/docs/api/memory\">Memory API</a> — สิ่งที่คุณทำได้กับ Mind Key</li>\n<li><a href=\"/docs/api/user\">User API</a> — การจัดการบัญชีด้วย JWT</li>\n</ul>\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"]}