# Autentikasi & Mind Keys

Synapse menggunakan dua metode autentikasi, masing-masing dioptimalkan untuk
kasus penggunaan yang berbeda. Memahami perbedaannya sangat penting untuk
membangun integrasi yang andal.

## Dua Metode Autentikasi

| Metode | Kasus Penggunaan | Rate Limit | Kedaluwarsa |
|--------|----------|------------|--------|
| **Mind Key** | Agen LLM, alat otomatis | Tidak ada (header) / 60 min (query) | Tidak pernah |
| **JWT** | UI untuk manusia, operasi akun | Tidak ada | 7 hari |

## Mind Key (untuk Agen)

Mind Key adalah token API dengan cakupan tenant. Token ini mengautentikasi data
satu mind (memori, tugas, chat, skrip, dll.). Gunakan untuk:

- Agen LLM yang memanggil API
- Skrip otomasi latar belakang
- Konfigurasi MCP server
- Integrasi berumur panjang apa pun

### Autentikasi header (disarankan)

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

### Parameter query (untuk alat yang hanya menggunakan URL)

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

> [!WARNING]
> Parameter query `?key=` di-rate-limit ke **60 permintaan per menit**.
> Header Bearer tidak memiliki rate limit. Gunakan header kapan pun klien Anda
> mendukung header khusus.

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

Respons menyertakan `mind_key` — **simpan segera**, hanya ditampilkan sekali.

### Mendaftar mind Anda

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

### Menghapus mind (ireversibel!)

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

## JWT (untuk Manusia)

JWT mengautentikasi **akun pengguna**, bukan mind spesifik. Gunakan untuk:

- Pendaftaran dan login akun
- Membuat / mendaftar / menghapus mind
- Berbagi mind dengan pengguna lain
- Manajemen langganan Web Push

### Daftar

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

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

Mengembalikan: `{ "jwt": "eyJ...", "user": {...} }`

### Kedaluwarsa JWT

JWT kedaluwarsa setelah **7 hari**. Saat JWT kedaluwarsa, cukup panggil `/login`
lagi untuk mendapatkan yang baru. Mind Key tidak pernah kedaluwarsa, sehingga
integrasi agen yang ada tetap berfungsi.

## Praktik Terbaik Keamanan

> [!CRITICAL]
> - **Jangan pernah commit Mind Key ke git.** Gunakan variabel lingkungan.
> - **Jangan pernah mencatat Mind Key.** Mask di log (`mk_***...***xyz`).
> - **Rotasi key** jika Anda mencurigai kebocoran (hapus mind, buat yang baru).
> - **Gunakan satu mind per proyek** untuk membatasi dampak jika key bocor.

### Pola variabel lingkungan

```bash
# .env (JANGAN PERNAH commit file ini)
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}` },
});
```

### Konfigurasi MCP server

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

## Pola Multi-Mind

Setiap pengguna dapat memiliki beberapa mind. Pola umum:

| Nama Mind | Tujuan |
|-----------|---------|
| `work` | Memori terkait pekerjaan |
| `personal` | Preferensi pribadi, keluarga |
| `project-synapse` | Konteks proyek spesifik |
| `learning-german` | Kemajuan belajar |
| `assistant-default` | Fallback tujuan umum |

Gunakan Mind Key yang berbeda untuk sesi LLM yang berbeda untuk menjaga konteks tetap terisolasi.

## Rate Limits

| Metode Auth | Batas | Cakupan |
|-------------|-------|-------|
| Mind Key (header) | Tidak ada | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | Tidak ada | Per-user |
| Endpoint publik | Tidak ada | Global |

Header rate limit (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)
disertakan dalam respons jika berlaku.

## Langkah Berikutnya

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — kapan menggunakan yang mana
- [Memory API](/docs/api/memory) — apa yang dapat Anda lakukan dengan Mind Key
- [User API](/docs/api/user) — manajemen akun dengan JWT