# Mind Key vs JWT — Kapan Menggunakan?

Synapse memiliki dua token autentikasi. Memilih yang salah menyebabkan error 401.
Panduan ini memberikan kerangka keputusan yang jelas.

## Tabel Keputusan Cepat

| Anda ingin... | Gunakan |
|----------------|-----|
| Menyimpan / recall memori | Mind Key |
| Mengirim / polling pesan chat | Mind Key |
| Mengelola tugas | Mind Key |
| Menyimpan skrip | Mind Key |
| Mendaftarkan webhook | Mind Key |
| Mengontrol komputer | Mind Key (sisi pengguna) / Computer Token (sisi agen) |
| Mendaftarkan akun pengguna | Tidak ada (publik) |
| Login | Tidak ada (publik) |
| Membuat / mendaftar / menghapus mind | JWT |
| Berbagi mind dengan pengguna lain | JWT |
| Berlangganan notifikasi web push | JWT |
| Melihat log audit | Mind Key |

## Aturan Sederhana

> [!TIP]
> **Jika menyentuh data satu mind → Mind Key.**
> **Jika mengelola akun atau metadata mind → JWT.**

## Mind Key — Token Akses Data

Mind Key memberikan akses ke **data satu mind**. Token berumur panjang yang
tidak pernah kedaluwarsa (sampai mind dihapus). Sempurna untuk:

- Agen LLM yang menyimpan memori lintas sesi
- Cron job latar belakang
- Konfigurasi MCP server
- Integrasi webhook
- Aplikasi mobile yang membaca memori

### Apa yang dapat dilakukan Mind Key

- `GET /memory/recall` — membaca semua memori dalam mind ini
- `POST /memory` — menyimpan/memperbarui memori
- `GET /chat/poll` — membaca pesan chat
- `POST /chat/reply` — mengirim pesan chat
- `GET /mind/tasks` — mendaftar tugas
- `POST /mind/task` — membuat tugas
- `POST /script` — menyimpan skrip
- `POST /webhooks` — mendaftarkan webhook
- `POST /computers/:id/commands` — mengantri perintah komputer

### Apa yang TIDAK dapat dilakukan Mind Key

- Membuat / mendaftar / menghapus mind (memerlukan JWT)
- Berbagi mind dengan pengguna lain (memerlukan JWT)
- Melihat info akun pengguna (memerlukan JWT)
- Berlangganan web push (memerlukan JWT)

## JWT — Token Manajemen Akun

JWT mengautentikasi **akun pengguna**. Kedaluwarsa setelah 7 hari dan digunakan
untuk operasi level akun yang mencakup beberapa mind atau melibatkan pengguna lain.

### Apa yang dapat dilakukan JWT

- `POST /minds` — membuat mind baru (mengembalikan Mind Key baru)
- `GET /minds` — mendaftar semua mind untuk pengguna ini
- `DELETE /minds/:id` — menghapus mind
- `POST /sharing` — berbagi mind dengan pengguna lain
- `POST /push/subscribe` — berlangganan notifikasi web push
- `GET /sharing` — mendaftar berbagi mind

### Apa yang TIDAK dapat dilakukan JWT

- Membaca / menulis memori (memerlukan Mind Key)
- Mengirim pesan chat (memerlukan Mind Key)
- Mengelola tugas (memerlukan Mind Key)
- Mendaftarkan webhook (memerlukan Mind Key)

## Kasus Khusus: Computer Token

Endpoint `/computers/me/*` (sisi agen, untuk screen-remote-agent)
menggunakan tipe token ketiga: **Computer Token**. Token ini dikembalikan oleh
`POST /computers/register` saat menukar kode instalasi, dan spesifik untuk
satu komputer terdaftar.

| Endpoint | Auth |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key atau JWT |
| `POST /computers/:id/commands` | Mind Key atau JWT |

## Pola Umum

### Pola 1: Agen LLM Tunggal

1. Daftar sekali → dapatkan JWT
2. Buat satu mind → dapatkan Mind Key
3. LLM menggunakan Mind Key untuk semuanya

### Pola 2: Agen Multi-Proyek

1. Daftar sekali → dapatkan JWT
2. Buat beberapa mind (kerja, pribadi, proyek-x) → dapatkan beberapa Mind Key
3. LLM memuat Mind Key berbeda berdasarkan konteks

### Pola 3: Berbagi Tim

1. Pengguna A membuat mind → dapatkan Mind Key A
2. Pengguna A berbagi dengan Pengguna B melalui JWT (`POST /sharing`)
3. Pengguna B sekarang dapat mengakses melalui JWT mereka sendiri
4. Untuk akses LLM, Pengguna B perlu membuat Mind Key mereka sendiri (atau menggunakan milik A)

### Pola 4: MCP Server

MCP server selalu menggunakan Mind Key (diatur melalui env var `SYNAPSE_MIND_KEY`). Satu instansi
MCP server = satu mind. Untuk akses multi-mind, jalankan beberapa instansi MCP
atau implementasikan peralihan mind sisi klien.

## Lembar Contoh Format Token

| Token | Format | Contoh |
|-------|--------|---------|
| Mind Key | `mk_` + 36 karakter | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 karakter | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Langkah Berikutnya

- [Autentikasi](/docs/getting-started/authentication) — panduan autentikasi lengkap
- [User & Minds API](/docs/api/user) — endpoint yang dilindungi JWT
- [Memory API](/docs/api/memory) — endpoint yang dilindungi Mind Key