# 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

| Method | Use Case | Rate Limit | Expiry |
|--------|----------|------------|--------|
| **Mind Key** | LLM agents, automated tools | None (header) / 60 min (query) | Never |
| **JWT** | Human-facing UI, account ops | None | 7 days |

## 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)

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

### Query parameter (for URL-only tools)

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

> [!WARNING]
> The `?key=` query parameter is rate-limited to **60 requests per minute**.
> The Bearer header has no rate limit. Use the header whenever your client
> supports custom headers.

### Creating a Mind Key

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

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

### Deleting a mind (irreversible!)

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

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

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

> [!CRITICAL]
> - **Never commit Mind Keys to git.** Use environment variables.
> - **Never log Mind Keys.** Mask them in logs (`mk_***...***xyz`).
> - **Rotate keys** if you suspect a leak (delete the mind, create a new one).
> - **Use one mind per project** to limit blast radius if a key leaks.

### Environment variable pattern

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

```typescript
// 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

```json
{
  "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:

| Mind Name | Purpose |
|-----------|---------|
| `work` | Job-related memories |
| `personal` | Personal preferences, family |
| `project-synapse` | Specific project context |
| `learning-german` | Learning progress |
| `assistant-default` | General-purpose fallback |

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

## Rate Limits

| Auth Method | Limit | Scope |
|-------------|-------|-------|
| Mind Key (header) | None | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | None | Per-user |
| Public endpoints | None | Global |

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

## Next Steps

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — when to use which
- [Memory API](/docs/api/memory) — what you can do with a Mind Key
- [User API](/docs/api/user) — account management with JWTs