{"title":"Autentikasi & Mind Keys","slug":"authentication","category":"getting-started","summary":"Bagaimana autentikasi Synapse bekerja: Mind Keys untuk agen, JWT untuk manusia, ?key= untuk alat yang hanya menggunakan URL.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":477,"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":"id","translated":true,"requested_lang":"id","content_markdown":"\n# Autentikasi & Mind Keys\n\nSynapse menggunakan dua metode autentikasi, masing-masing dioptimalkan untuk\nkasus penggunaan yang berbeda. Memahami perbedaannya sangat penting untuk\nmembangun integrasi yang andal.\n\n## Dua Metode Autentikasi\n\n| Metode | Kasus Penggunaan | Rate Limit | Kedaluwarsa |\n|--------|----------|------------|--------|\n| **Mind Key** | Agen LLM, alat otomatis | Tidak ada (header) / 60 min (query) | Tidak pernah |\n| **JWT** | UI untuk manusia, operasi akun | Tidak ada | 7 hari |\n\n## Mind Key (untuk Agen)\n\nMind Key adalah token API dengan cakupan tenant. Token ini mengautentikasi data\nsatu mind (memori, tugas, chat, skrip, dll.). Gunakan untuk:\n\n- Agen LLM yang memanggil API\n- Skrip otomasi latar belakang\n- Konfigurasi MCP server\n- Integrasi berumur panjang apa pun\n\n### Autentikasi header (disarankan)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Parameter query (untuk alat yang hanya menggunakan URL)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Parameter query `?key=` di-rate-limit ke **60 permintaan per menit**.\n> Header Bearer tidak memiliki rate limit. Gunakan header kapan pun klien Anda\n> mendukung header khusus.\n\n### Membuat 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\nRespons menyertakan `mind_key` — **simpan segera**, hanya ditampilkan sekali.\n\n### Mendaftar mind Anda\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Menghapus mind (ireversibel!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (untuk Manusia)\n\nJWT mengautentikasi **akun pengguna**, bukan mind spesifik. Gunakan untuk:\n\n- Pendaftaran dan login akun\n- Membuat / mendaftar / menghapus mind\n- Berbagi mind dengan pengguna lain\n- Manajemen langganan Web Push\n\n### Daftar\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\nMengembalikan: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Login\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\nMengembalikan: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Kedaluwarsa JWT\n\nJWT kedaluwarsa setelah **7 hari**. Saat JWT kedaluwarsa, cukup panggil `/login`\nlagi untuk mendapatkan yang baru. Mind Key tidak pernah kedaluwarsa, sehingga\nintegrasi agen yang ada tetap berfungsi.\n\n## Praktik Terbaik Keamanan\n\n> [!CRITICAL]\n> - **Jangan pernah commit Mind Key ke git.** Gunakan variabel lingkungan.\n> - **Jangan pernah mencatat Mind Key.** Mask di log (`mk_***...***xyz`).\n> - **Rotasi key** jika Anda mencurigai kebocoran (hapus mind, buat yang baru).\n> - **Gunakan satu mind per proyek** untuk membatasi dampak jika key bocor.\n\n### Pola variabel lingkungan\n\n```bash\n# .env (JANGAN PERNAH commit file ini)\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### Konfigurasi 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## Pola Multi-Mind\n\nSetiap pengguna dapat memiliki beberapa mind. Pola umum:\n\n| Nama Mind | Tujuan |\n|-----------|---------|\n| `work` | Memori terkait pekerjaan |\n| `personal` | Preferensi pribadi, keluarga |\n| `project-synapse` | Konteks proyek spesifik |\n| `learning-german` | Kemajuan belajar |\n| `assistant-default` | Fallback tujuan umum |\n\nGunakan Mind Key yang berbeda untuk sesi LLM yang berbeda untuk menjaga konteks tetap terisolasi.\n\n## Rate Limits\n\n| Metode Auth | Batas | Cakupan |\n|-------------|-------|-------|\n| Mind Key (header) | Tidak ada | Per-mind |\n| Mind Key (?key=) | 60/min | Per-IP |\n| JWT (header) | Tidak ada | Per-user |\n| Endpoint publik | Tidak ada | Global |\n\nHeader rate limit (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)\ndisertakan dalam respons jika berlaku.\n\n## Langkah Berikutnya\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — kapan menggunakan yang mana\n- [Memory API](/docs/api/memory) — apa yang dapat Anda lakukan dengan Mind Key\n- [User API](/docs/api/user) — manajemen akun dengan JWT\n","content_html":"

Autentikasi & Mind Keys

\n

Synapse menggunakan dua metode autentikasi, masing-masing dioptimalkan untuk\nkasus penggunaan yang berbeda. Memahami perbedaannya sangat penting untuk\nmembangun integrasi yang andal.

\n

Dua Metode Autentikasi

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MetodeKasus PenggunaanRate LimitKedaluwarsa
Mind KeyAgen LLM, alat otomatisTidak ada (header) / 60 min (query)Tidak pernah
JWTUI untuk manusia, operasi akunTidak ada7 hari
\n

Mind Key (untuk Agen)

\n

Mind Key adalah token API dengan cakupan tenant. Token ini mengautentikasi data\nsatu mind (memori, tugas, chat, skrip, dll.). Gunakan untuk:

\n\n

Autentikasi header (disarankan)

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

Parameter query (untuk alat yang hanya menggunakan URL)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
Parameter query `?key=` di-rate-limit ke **60 permintaan per menit**.\nHeader Bearer tidak memiliki rate limit. Gunakan header kapan pun klien Anda\nmendukung header khusus.

Membuat 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"}'

Respons menyertakan mind_key — simpan segera, hanya ditampilkan sekali.

\n

Mendaftar mind Anda

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

Menghapus mind (ireversibel!)

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

JWT (untuk Manusia)

\n

JWT mengautentikasi akun pengguna, bukan mind spesifik. Gunakan untuk:

\n\n

Daftar

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

Mengembalikan: { "jwt": "eyJ...", "user": {...} }

\n

Login

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

Mengembalikan: { "jwt": "eyJ...", "user": {...} }

\n

Kedaluwarsa JWT

\n

JWT kedaluwarsa setelah 7 hari. Saat JWT kedaluwarsa, cukup panggil /login\nlagi untuk mendapatkan yang baru. Mind Key tidak pernah kedaluwarsa, sehingga\nintegrasi agen yang ada tetap berfungsi.

\n

Praktik Terbaik Keamanan

\n

Pola variabel lingkungan

\n
# .env (JANGAN PERNAH commit file ini)\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});

Konfigurasi MCP server

\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}

Pola Multi-Mind

\n

Setiap pengguna dapat memiliki beberapa mind. Pola umum:

\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
Nama MindTujuan
workMemori terkait pekerjaan
personalPreferensi pribadi, keluarga
project-synapseKonteks proyek spesifik
learning-germanKemajuan belajar
assistant-defaultFallback tujuan umum
\n

Gunakan Mind Key yang berbeda untuk sesi LLM yang berbeda untuk menjaga konteks tetap terisolasi.

\n

Rate Limits

\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
Metode AuthBatasCakupan
Mind Key (header)Tidak adaPer-mind
Mind Key (?key=)60/minPer-IP
JWT (header)Tidak adaPer-user
Endpoint publikTidak adaGlobal
\n

Header rate limit (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After)\ndisertakan dalam respons jika berlaku.

\n

Langkah Berikutnya

\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"]}