# Mind Key vs JWT — What When?
SUMMARY: Decision guide: Mind Key for agent data access, JWT for account management.

KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).

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
| You want to... | Use |
|----------------|-----|
| Store / recall memories | Mind Key |
| Send / poll chat messages | Mind Key |
| Manage tasks | Mind Key |
| Store scripts | Mind Key |
| Register webhooks | Mind Key |
| Control computers | Mind Key (user-side) / Computer Token (agent-side) |
| Register a user account | None (public) |
| Login | None (public) |
| Create / list / delete minds | JWT |
| Share a mind with another user | JWT |
| Subscribe to web push notifications | JWT |
| View audit log | Mind Key |
The Simple Rule
> [!TIP]
> If it touches a single mind's data → Mind Key.
> If it manages the account or mind metadata → JWT.
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
-  — read all memories in this mind
-  — store/update memories
-  — read chat messages
-  — send chat messages
-  — list tasks
-  — create tasks
-  — store scripts
-  — register webhooks
-  — 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
-  — create a new mind (returns a new Mind Key)
-  — list all minds for this user
-  — delete a mind
-  — share a mind with another user
-  — subscribe to web push notifications
-  — 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  endpoints (agent-facing, for the screen-remote-agent)
use a third token type: the Computer Token. This token is returned by
 when redeeming an install code, and is specific to
one registered computer.
| Endpoint | Auth |
|----------|------|
|  | Computer Token |
|  | Computer Token |
|  | Mind Key or JWT |
|  | Mind Key or JWT |
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 ()
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  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
| Token | Format | Example |
|-------|--------|---------|
| Mind Key |  + 36 chars |  |
| JWT |  + base64 |  |
| Computer Token |  + 36 chars |  |
Next Steps
- Authentication — full auth guide
- User & Minds API — JWT-protected endpoints
- Memory API — Mind Key-protected endpoints