# प्रमाणीकरण और Mind Keys

Synapse दो प्रमाणीकरण विधियों का उपयोग करता है, प्रत्येक अलग उपयोग के मामले के लिए अनुकूलित। विश्वसनीय इंटीग्रेशन बनाने के लिए अंतर को समझना आवश्यक है।

## दो प्रमाणीकरण विधियाँ

| विधि | उपयोग का मामला | रेट लिमिट | समाप्ति |
|--------|----------|------------|--------|
| **Mind Key** | LLM एजेंट्स, स्वचालित टूल्स | 120/min (बाहरी Bearer); ?key= डिफ़ॉल्ट रूप से अक्षम (deny) | कभी नहीं |
| **JWT** | मानव-सामने UI, खाता ऑप्स | 120/min (बाहरी IPs) | 7 दिन |

## Mind Key (एजेंट्स के लिए)

Mind Key एक टैनेंट-स्कोप्ड API टोकन है। यह एकल mind के डेटा (मेमोरीज़, कार्य, चैट, स्क्रिप्ट्स, आदि) को प्रमाणित करता है। इसका उपयोग करें:

- API कॉल करने वाले LLM एजेंट्स
- बैकग्राउंड ऑटोमेशन स्क्रिप्ट्स
- MCP server कॉन्फ़िगरेशन
- कोई भी दीर्घ-जीवित इंटीग्रेशन

### हेडर प्रमाणीकरण (अनुशंसित)

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

### क्वेरी पैरामीटर (डिफ़ॉल्ट रूप से अक्षम)

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

> [!WARNING]
> `?key=` क्वेरी पैरामीटर हार्डन्ड डिफ़ॉल्ट `AUTH_QUERY_KEY_MODE=deny` से **अक्षम** है: सर्वर `?key=` पर
> 401 और संकेत "Query-param auth (?key=) is disabled" के साथ उत्तर देता है। Bearer-केवल ही सुरक्षित डिफ़ॉल्ट है (SSOT: `src/lib/auth.ts`)।
> केवल जब कोई ऑपरेटर स्पष्ट रूप से `AUTH_QUERY_KEY_MODE=allow` सेट करे, तभी `?key=` 60 req/min
> (प्रति IP) के संक्रमण वाल्व के रूप में काम करता है। बाहरी Bearer क्लाइंट प्रति पहचान 120 req/min
> पाते हैं; विश्वसनीय आंतरिक नेटवर्क असीमित हैं।

### 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"}'
```

प्रतिक्रिया में `mind_key` शामिल है — **इसे तुरंत सहेजें**, यह केवल एक बार दिखाई जाती है।

### अपने minds की सूची बनाना

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

### Mind हटाना (अपरिवर्तनीय!)

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

## JWT (मानवों के लिए)

JWT विशिष्ट mind नहीं, बल्कि **उपयोगकर्ता खाते** को प्रमाणित करते हैं। इनका उपयोग करें:

- खाता पंजीकरण और लॉगिन
- Minds बनाने / सूचीबद्ध करने / हटाने
- अन्य उपयोगकर्ताओं के साथ minds साझा करने
- Web Push सब्सक्रिप्शन प्रबंधन

### पंजीकरण

```bash
curl -X POST https://synapse.schaefer.zone/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

लौटाता है: `{ "jwt": "eyJ...", "user": {...} }`

### लॉगिन

```bash
curl -X POST https://synapse.schaefer.zone/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

लौटाता है: `{ "jwt": "eyJ...", "user": {...} }`

### JWT समाप्ति

JWT **7 दिनों** के बाद समाप्त होते हैं। JWT समाप्त होने पर, नया प्राप्त करने के लिए बस `/login` फिर से कॉल करें। Mind Key कभी समाप्त नहीं होती, इसलिए मौजूदा एजेंट इंटीग्रेशन काम करते रहते हैं।

## सुरक्षा सर्वोत्तम प्रथाएँ

> [!CRITICAL]
> - **Mind Keys कभी git में कमिट न करें।** पर्यावरण वेरिएबल्स का उपयोग करें।
> - **Mind Keys कभी लॉग न करें।** लॉग में उन्हें मास्क करें (`mk_***...***xyz`)।
> - **लीक के संदेह होने पर keys रोटेट करें** (mind हटाएँ, नया बनाएँ)।
> - **प्रति परियोजना एक mind का उपयोग करें** ताकि लीक होने पर प्रभाव सीमित रहे।

### पर्यावरण वेरिएबल पैटर्न

```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"
      }
    }
  }
}
```

## मल्टी-Mind पैटर्न

प्रत्येक उपयोगकर्ता के पास कई minds हो सकते हैं। सामान्य पैटर्न:

| Mind नाम | उद्देश्य |
|-----------|---------|
| `work` | कार्य-संबंधी मेमोरीज़ |
| `personal` | व्यक्तिगत प्राथमिकताएँ, परिवार |
| `project-synapse` | विशिष्ट परियोजना संदर्भ |
| `learning-german` | सीखने की प्रगति |
| `assistant-default` | सामान्य-उद्देश्य fallback |

संदर्भ अलग रखने के लिए विभिन्न LLM सत्रों के लिए विभिन्न Mind Keys का उपयोग करें।

## रेट लिमिट

| प्रमाणीकरण विधि | सीमा | दायरा |
|-------------|-------|-------|
| Mind Key (हेडर) | 120/min बाहरी IPs से (प्रति पहचान); विश्वसनीय आंतरिक नेटवर्क के लिए असीमित | प्रति-mind |
| Mind Key (?key=, केवल allow पर) | 60/min | प्रति-IP |
| JWT (हेडर) | 120 req/min (बाहरी IPs; विश्वसनीय आंतरिक नेटवर्क के लिए असीमित) | प्रति-उपयोगकर्ता |
| सार्वजनिक एंडपॉइंट्स | कोई नहीं | वैश्विक |

रेट लिमिट हेडर (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`) जब लागू हो तब प्रतिक्रियाओं में शामिल होते हैं।

## अगले कदम

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — कब क्या उपयोग करें
- [Memory API](/docs/api/memory) — Mind Key से आप क्या कर सकते हैं
- [User API](/docs/api/user) — JWTs के साथ खाता प्रबंधन