# Authentication & Mind Keys
SUMMARY: How Synapse authentication works: Mind Keys for agents, JWTs for humans, ?key= for URL-only tools.

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

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)
[CODE BLOCK]
Query parameter (for URL-only tools)
[CODE BLOCK]
> [!WARNING]
> The  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
[CODE BLOCK]
Response includes  — save it immediately, it's shown only once.
Listing your minds
[CODE BLOCK]
Deleting a mind (irreversible!)
[CODE BLOCK]
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
[CODE BLOCK]
Returns: 
Login
[CODE BLOCK]
Returns: 
JWT expiry
JWTs expire after 7 days. When a JWT expires, simply call  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 ().
> - 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
[CODE BLOCK]
[CODE BLOCK]
MCP server config
[CODE BLOCK]
Multi-Mind Pattern
Each user can have multiple minds. Common patterns:
| Mind Name | Purpose |
|-----------|---------|
|  | Job-related memories |
|  | Personal preferences, family |
|  | Specific project context |
|  | Learning progress |
|  | 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 (, , )
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