# Kimlik Doğrulama & Mind Key'ler

Synapse, her biri farklı bir kullanım senaryosu için optimize edilmiş iki kimlik doğrulama yöntemi kullanır. Güvenilir entegrasyonlar oluşturmak için farkı anlamak esastır.

## İki Kimlik Doğrulama Yöntemi

| Yöntem | Kullanım Senaryosu | Hız Sınırı | Son Kullanma |
|--------|----------|------------|--------|
| **Mind Key** | LLM ajanları, otomatik araçlar | Yok (header) / 60 dk (sorgu) | Asla |
| **JWT** | İnsana yönelik arayüz, hesap işlemleri | Yok | 7 gün |

## Mind Key (Ajanlar için)

Mind Key, kiracı kapsamlı bir API token'ıdır. Tek bir mind'in verilerini (bellekler, görevler, sohbet, betikler vb.) doğrular. Şunlar için kullanın:

- API çağrısı yapan LLM ajanları
- Arka plan otomasyon betikleri
- MCP sunucu yapılandırması
- Herhangi bir uzun ömürlü entegrasyon

### Header kimlik doğrulaması (önerilir)

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

### Sorgu parametresi (yalnızca URL kullanan araçlar için)

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

> [!WARNING]
> `?key=` sorgu parametresi **dakikada 60 istek** ile sınırlıdır. Bearer header'ın hız sınırı yoktur. İstemciniz özel başlıkları desteklediğinde header'ı kullanın.

### Mind Key Oluşturma

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

Yanıt `mind_key` içerir — **hemen kaydedin**, yalnızca bir kez gösterilir.

### Mind'lerinizi listeleme

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

### Bir mind'i silme (geri alınamaz!)

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

## JWT (İnsanlar için)

JWT'ler belirli bir mind'i değil, **kullanıcı hesabını** doğrular. Şunlar için kullanın:

- Hesap kaydı ve giriş
- Mind oluşturma / listeleme / silme
- Mind'leri diğer kullanıcılarla paylaşma
- Web Push abonelik yönetimi

### Kaydol

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

Döndürür: `{ "jwt": "eyJ...", "user": {...} }`

### Giriş

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

Döndürür: `{ "jwt": "eyJ...", "user": {...} }`

### JWT son kullanma

JWT'ler **7 gün** sonra sona erer. Bir JWT sona erdiğinde, yenisini almak için `/login` çağırın. Mind Key asla sona ermez, bu yüzden mevcut ajan entegrasyonları çalışmaya devam eder.

## Güvenlik En İyi Uygulamaları

> [!CRITICAL]
> - **Mind Key'leri asla git'e commit etmeyin.** Ortam değişkenleri kullanın.
> - **Mind Key'leri asla loglamayın.** Loglarda maskeleyin (`mk_***...***xyz`).
> - Bir sızıntıdan şüphelenirseniz **anahtarları döndürün** (mind'i silin, yeni oluşturun).
> - Bir anahtar sızarsa etki alanını sınırlamak için **proje başına bir mind** kullanın.

### Ortam değişkeni deseni

```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 sunucu yapılandırması

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}
```

## Çoklu Mind Deseni

Her kullanıcı birden çok mind'e sahip olabilir. Yaygın desenler:

| Mind Adı | Amaç |
|-----------|---------|
| `work` | İşle ilgili bellekler |
| `personal` | Kişisel tercihler, aile |
| `project-synapse` | Belirli proje bağlamı |
| `learning-german` | Öğrenme ilerlemesi |
| `assistant-default` | Genel amaçlı yedek |

Bağlamları izole tutmak için farklı LLM oturumlarında farklı Mind Key'ler kullanın.

## Hız Sınırları

| Kimlik Doğrulama Yöntemi | Sınır | Kapsam |
|-------------|-------|-------|
| Mind Key (header) | Yok | Mind başına |
| Mind Key (?key=) | 60/dakika | IP başına |
| JWT (header) | Yok | Kullanıcı başına |
| Herkese açık uç noktalar | Yok | Global |

Hız sınırı başlıkları (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`) uygun olduğunda yanıtlara dahil edilir.

## Sonraki Adımlar

- [Mind Key ve JWT](/docs/getting-started/mind-key-vs-jwt) — hangisi ne zaman kullanılır
- [Memory API](/docs/api/memory) — bir Mind Key ile neler yapabilirsiniz
- [User API](/docs/api/user) — JWT'lerle hesap yönetimi