{"title":"Authentication & Mind Keys","slug":"authentication","category":"getting-started","summary":"How Synapse authentication works: Mind Keys for agents, JWTs for humans, ?key= for URL-only tools.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":476,"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":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Authentication & Mind Keys\n\nSynapse uses two authentication methods, each optimized for a different use case.\nUnderstanding the difference is essential for building reliable integrations.\n\n## Two Auth Methods\n\n| Method | Use Case | Rate Limit | Expiry |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM agents, automated tools | None (header) / 60 min (query) | Never |\n| **JWT** | Human-facing UI, account ops | None | 7 days |\n\n## Mind Key (for Agents)\n\nA Mind Key is a tenant-scoped API token. It authenticates a single mind's data\n(memories, tasks, chat, scripts, etc.). Use it for:\n\n- LLM agents calling the API\n- Background automation scripts\n- MCP server configuration\n- Any long-lived integration\n\n### Header authentication (recommended)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Query parameter (for URL-only tools)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> The `?key=` query parameter is rate-limited to **60 requests per minute**.\n> The Bearer header has no rate limit. Use the header whenever your client\n> supports custom headers.\n\n### Creating a 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 includes `mind_key` — **save it immediately**, it's shown only once.\n\n### Listing your minds\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Deleting a mind (irreversible!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (for Humans)\n\nJWTs authenticate the **user account**, not a specific mind. Use them for:\n\n- Account registration and login\n- Creating / listing / deleting minds\n- Sharing minds with other users\n- Web Push subscription management\n\n### Register\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\nReturns: `{ \"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\nReturns: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### JWT expiry\n\nJWTs expire after **7 days**. When a JWT expires, simply call `/login` again to\nget a fresh one. The Mind Key never expires, so existing agent integrations\nkeep working.\n\n## Security Best Practices\n\n> [!CRITICAL]\n> - **Never commit Mind Keys to git.** Use environment variables.\n> - **Never log Mind Keys.** Mask them in logs (`mk_***...***xyz`).\n> - **Rotate keys** if you suspect a leak (delete the mind, create a new one).\n> - **Use one mind per project** to limit blast radius if a key leaks.\n\n### Environment variable pattern\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 config\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 Pattern\n\nEach user can have multiple minds. Common patterns:\n\n| Mind Name | Purpose |\n|-----------|---------|\n| `work` | Job-related memories |\n| `personal` | Personal preferences, family |\n| `project-synapse` | Specific project context |\n| `learning-german` | Learning progress |\n| `assistant-default` | General-purpose fallback |\n\nUse different Mind Keys for different LLM sessions to keep contexts isolated.\n\n## Rate Limits\n\n| Auth Method | 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 endpoints | None | Global |\n\nRate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)\nare included in responses when applicable.\n\n## Next Steps\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — when to use which\n- [Memory API](/docs/api/memory) — what you can do with a Mind Key\n- [User API](/docs/api/user) — account management with JWTs\n","content_html":"

Authentication & Mind Keys

\n

Synapse uses two authentication methods, each optimized for a different use case.\nUnderstanding the difference is essential for building reliable integrations.

\n

Two Auth Methods

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MethodUse CaseRate LimitExpiry
Mind KeyLLM agents, automated toolsNone (header) / 60 min (query)Never
JWTHuman-facing UI, account opsNone7 days
\n

Mind Key (for Agents)

\n

A Mind Key is a tenant-scoped API token. It authenticates a single mind's data\n(memories, tasks, chat, scripts, etc.). Use it for:

\n\n

Header authentication (recommended)

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

Query parameter (for URL-only tools)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
The `?key=` query parameter is rate-limited to **60 requests per minute**.\nThe Bearer header has no rate limit. Use the header whenever your client\nsupports custom headers.

Creating a 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"}'

Response includes mind_key — save it immediately, it's shown only once.

\n

Listing your minds

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

Deleting a mind (irreversible!)

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

JWT (for Humans)

\n

JWTs authenticate the user account, not a specific mind. Use them for:

\n\n

Register

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

Returns: { "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"}'

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

\n

JWT expiry

\n

JWTs expire after 7 days. When a JWT expires, simply call /login again to\nget a fresh one. The Mind Key never expires, so existing agent integrations\nkeep working.

\n

Security Best Practices

\n

Environment variable pattern

\n
# .env (NEVER commit this file)\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 server config

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

Multi-Mind Pattern

\n

Each user can have multiple minds. Common patterns:

\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 NamePurpose
workJob-related memories
personalPersonal preferences, family
project-synapseSpecific project context
learning-germanLearning progress
assistant-defaultGeneral-purpose fallback
\n

Use different Mind Keys for different LLM sessions to keep contexts isolated.

\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
Auth MethodLimitScope
Mind Key (header)NonePer-mind
Mind Key (?key=)60/minPer-IP
JWT (header)NonePer-user
Public endpointsNoneGlobal
\n

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After)\nare included in responses when applicable.

\n

Next Steps

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