# 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

- `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.

| Endpoint | Auth |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key or JWT |
| `POST /computers/:id/commands` | 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 (`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

| Token | Format | Example |
|-------|--------|---------|
| Mind Key | `mk_` + 36 chars | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 chars | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Next Steps

- [Authentication](/docs/getting-started/authentication) — full auth guide
- [User & Minds API](/docs/api/user) — JWT-protected endpoints
- [Memory API](/docs/api/memory) — Mind Key-protected endpoints