Mind Key vs JWT — What When?

Synapse has two authentication tokens. Choosing the wrong one leads to 401 errors. This guide gives you a clear decision framework.

Quick Decision Table

The Simple Rule

Mind Key — Data Access Token

A Mind Key grants access to one mind's data. It's a long-lived token that never expires (until the mind is deleted). Perfect for:

• LLM agents persisting memories across sessions
• Background cron jobs
• MCP server configuration
• Webhook integrations
• Mobile apps reading memory

What Mind Key can do

• GET /memory/recall — read all memories in this mind
• POST /memory — store/update memories
• GET /chat/poll — read chat messages
• POST /chat/reply — send chat messages
• GET /mind/tasks — list tasks
• POST /mind/task — create tasks
• POST /script — store scripts
• POST /webhooks — register webhooks
• POST /computers/:id/commands — queue computer commands

What Mind Key CANNOT do

• Create / list / delete minds (need JWT)
• Share mind with another user (need JWT)
• View user account info (need JWT)
• Subscribe to web push (need JWT)

JWT — Account Management Token

A JWT authenticates the user account. It expires after 7 days and is used for account-level operations that span multiple minds or involve other users.

What JWT can do

• POST /minds — create a new mind (returns a new Mind Key)
• GET /minds — list all minds for this user
• DELETE /minds/:id — delete a mind
• POST /sharing — share a mind with another user
• POST /push/subscribe — subscribe to web push notifications
• GET /sharing — list mind shares

What JWT CANNOT do

• Read / write memories (need Mind Key)
• Send chat messages (need Mind Key)
• Manage tasks (need Mind Key)
• Register webhooks (need Mind Key)

Special Case: Computer Token

The /computers/me/* endpoints (agent-facing, for the screen-remote-agent) use a third token type: the Computer Token. This token is returned by POST /computers/register when redeeming an install code, and is specific to one registered computer.

Common Patterns

Pattern 1: Single LLM Agent

1. Register once → get JWT
2. Create one mind → get Mind Key
3. LLM uses Mind Key for everything

Pattern 2: Multi-Project Agent

1. Register once → get JWT
2. Create multiple minds (work, personal, project-x) → get multiple Mind Keys
3. LLM loads different Mind Key based on context

Pattern 3: Team Sharing

1. User A creates a mind → gets Mind Key A
2. User A shares with User B via JWT (POST /sharing)
3. User B can now access via their own JWT
4. For LLM access, User B needs to create their own Mind Key (or use A's)

Pattern 4: MCP Server

MCP servers always use Mind Key (set via SYNAPSE_MIND_KEY env var). One MCP server instance = one mind. For multi-mind access, run multiple MCP instances or implement client-side mind switching.

Token Format Cheat Sheet

Next Steps

• Authentication — full auth guide
• User & Minds API — JWT-protected endpoints
• Memory API — Mind Key-protected endpoints