Authentication & Mind Keys

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

Two Auth Methods

Mind Key (for Agents)

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

• LLM agents calling the API
• Background automation scripts
• MCP server configuration
• Any long-lived integration

Header authentication (recommended)

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

Query parameter (for URL-only tools)

curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere

Creating a Mind Key

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

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

Listing your minds

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

Deleting a mind (irreversible!)

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

JWT (for Humans)

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

• Account registration and login
• Creating / listing / deleting minds
• Sharing minds with other users
• Web Push subscription management

Register

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

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

Login

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

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

JWT expiry

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

Security Best Practices

Environment variable pattern

# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone

// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});

MCP server config

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}

Multi-Mind Pattern

Each user can have multiple minds. Common patterns:

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

Rate Limits

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

Next Steps

• Mind Key vs JWT — when to use which
• Memory API — what you can do with a Mind Key
• User API — account management with JWTs