> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Autentikasi

> Lindungi API dengan Basic Auth, lalu tautkan setiap akun WhatsApp melalui kode QR, kode penautan, atau passkey.

GOWA memiliki dua jenis autentikasi yang terpisah:

1. **Akses API**: siapa yang boleh memanggil GOWA. Ini menggunakan HTTP Basic Auth.
2. **Penautan WhatsApp**: menautkan akun WhatsApp ke slot perangkat, seperti saat menautkan WhatsApp Web.

## Akses API: Basic Auth

Basic Auth adalah satu-satunya metode autentikasi API. Tidak ada API key atau JWT untuk panggilan REST.

Tetapkan satu atau beberapa pasangan `user:password`, dipisahkan dengan koma:

```bash theme={null}
# environment
APP_BASIC_AUTH=admin:changeme,ops:another-secret
# or flag
./whatsapp rest --basic-auth=admin:changeme,ops:another-secret
```

Setiap entri harus berisi nama pengguna dan kata sandi yang tidak kosong. Listener bawaan, `APP_HOST=0.0.0.0`, menolak dijalankan tanpa kredensial lengkap. Untuk pengembangan lokal tanpa autentikasi, gunakan alamat bind `APP_HOST=127.0.0.1`.

Jika reverse proxy mengautentikasi setiap pemanggil, `APP_ALLOW_UNAUTHENTICATED=true` atau `--allow-unauthenticated=true` secara eksplisit mengizinkan listener non-loopback tanpa Basic Auth. Batasi akses langsung ke listener tersebut.

Kirim kredensial pada setiap permintaan:

```bash theme={null}
curl -u admin:changeme http://localhost:3000/app/info
# same as
curl -H "Authorization: Basic YWRtaW46Y2hhbmdlbWU=" http://localhost:3000/app/info
```

Kredensial yang tidak disertakan atau salah menghasilkan `401 Unauthorized`.

### Rute yang tidak dilindungi Basic Auth

| Rute | Alasan |
| - | - |
| `GET /health` | Probe liveness. Selalu di root, mengabaikan `APP_BASE_PATH`. |
| `POST /chatwoot/webhook`, `POST /chatwoot/webhook/{device_id}` | Dipanggil oleh Chatwoot. Hanya didaftarkan saat `CHATWOOT_ENABLED=true` dan dilindungi oleh `CHATWOOT_WEBHOOK_SECRET` sebagai penggantinya. Lihat [Chatwoot](https://gowa-docs.mintlify.site/id/integrations/chatwoot.md). |
| Penemuan OAuth MCP dan endpoint `/oauth/*` | Hanya saat `MCP_OAUTH_ENABLED=true`. Lihat [Server MCP](https://gowa-docs.mintlify.site/id/integrations/mcp.md). |
| `GET /statics/*` | Gambar QR, unggahan, dan media yang diunduh. Disajikan sebelum Basic Auth. Siapa pun yang mengetahui URL berkas dapat mengambilnya. Hanya berkas JPEG, PNG, GIF, dan WebP yang tervalidasi pada path gambar yang ditampilkan langsung. Berkas lain diunduh sebagai lampiran dengan tipe konten nonaktif dan `X-Content-Type-Options: nosniff`. Batasi akses berkas pada proxy jika diperlukan. |

Semua rute lainnya, termasuk dasbor di `/`, `/mcp`, dan `/ws`, memerlukan Basic Auth jika dikonfigurasi.

### WebSocket

Browser tidak dapat menetapkan header pada koneksi WebSocket, sehingga `/ws` menerima kredensial dalam query string:

```text theme={null}
ws://localhost:3000/ws?device_id=my-device&authorization=YWRtaW46Y2hhbmdlbWU=
```

`authorization` adalah `base64(user:password)`. Gunakan TLS (`wss://`) dan samarkan query string dalam log proxy. WebSocket memeriksa origin browser terhadap origin tepercaya yang sama dengan yang digunakan untuk permintaan HTTP pengubah status. Hub WebSocket saat ini menyiarkan peristiwa ke semua socket yang terhubung. Query `device_id` memilih konteks perangkat untuk koneksi, tetapi tidak mengisolasi pengiriman peristiwa. Gunakan pengenal perangkat pada peristiwa untuk memfilter tampilan dasbor, dan berikan akses API hanya kepada pemanggil yang dipercaya untuk mengakses semua perangkat.

Lihat [referensi WebSocket](https://gowa-docs.mintlify.site/id/api-reference/websocket.md) untuk kode peristiwa, payload, dan contoh klien.

### CORS

CORS mengizinkan semua origin secara bawaan. Batasi dengan `APP_CORS_ALLOWED_ORIGINS=https://ui.example.com` (dipisahkan dengan koma). Header permintaan yang diizinkan adalah `Origin`, `Content-Type`, `Accept`, `Authorization`, dan `X-Device-Id`.

CORS dan pemeriksaan origin browser merupakan hal terpisah. Origin CORS wildcard tidak memberikan izin untuk permintaan pengubah status atau WebSocket. GOWA mempercayai host permintaan itu sendiri, origin CORS tertentu, `APP_TRUSTED_ORIGINS`, serta origin yang dikonfigurasi untuk penerbit OAuth dan URL callback Chatwoot. Untuk dasbor terpisah, konfigurasikan origin persisnya:

```env theme={null}
APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
APP_TRUSTED_ORIGINS=https://ui.example.com
```

Mutasi dari browser yang tidak dipercaya menghasilkan `403 CROSS_SITE_REQUEST_BLOCKED`. Ini juga mencakup rute GET yang melakukan login, logout, menghubungkan ulang, atau mereset tautan undangan. Klien seperti curl yang tidak mengirim header origin browser tetap berfungsi.

Origin `null` tidak pernah dipercaya. Sajikan `gowa-ui.html` melalui HTTP atau HTTPS alih-alih membukanya sebagai URL `file://`. Di belakang reverse proxy, pertahankan `Host`, konfigurasikan proxy tepercaya dengan `X-Forwarded-Host`, atau cantumkan origin publik dalam `APP_TRUSTED_ORIGINS`.

## Penautan WhatsApp

Setiap akun WhatsApp menempati satu **slot perangkat**. Buat slot terlebih dahulu, lalu tautkan. Rute di bawah `/devices/{device_id}` mengambil perangkat dari path. Rute `/app/*` yang setara menggunakan header `X-Device-Id`.

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/devices \
  -H "Content-Type: application/json" -d '{"device_id": "sales"}'
```

### Kode QR

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/login
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Login success",
  "results": {
    "device_id": "sales",
    "qr_link": "http://localhost:3000/statics/qrcode/scan-qr-b0b7bb43-....png",
    "qr_duration": 30
  }
}
```

Buka `qr_link` dan pindai dari ponsel: **Setelan → Perangkat tertaut → Tautkan perangkat**. Minta kode baru setelah `qr_duration` detik. Dasbor di `/` menampilkan QR secara langsung dan diperbarui secara real time melalui WebSocket.

### Kode penautan

```bash theme={null}
curl -u admin:changeme -X POST \
  "http://localhost:3000/devices/sales/login/code?phone=628123456789"
```

Respons berisi `results.pair_code`, yaitu kode 8 karakter. Di ponsel, pilih **Tautkan dengan nomor telepon saja** dan masukkan kode tersebut. `phone` harus berupa nomor akun yang ditautkan, beserta kode negara.

### Passkey

Jika ponsel meminta verifikasi passkey saat login QR, GOWA menyimpan challenge WebAuthn dan menyiarkan `PASSKEY_REQUEST` melalui WebSocket. Dasbor menangani alur ini. Untuk menjalankannya sendiri:

1. `GET /app/passkey` mengembalikan challenge yang menunggu.
2. `POST /app/passkey/response` mengirim assertion WebAuthn (format `PublicKeyCredential.toJSON()`).
3. Tunggu `PASSKEY_CONFIRMATION`. Saat `result.skip_handoff_ux` bernilai true, alur QR aktif mengirim konfirmasi secara otomatis. Jika tidak, bandingkan `result.code` dengan kode di ponsel, lalu panggil `POST /app/passkey/confirm`.

Kirim `X-Device-Id` pada ketiga panggilan tersebut.

### Periksa hasilnya

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/status
```

`results.is_connected` dan `results.is_logged_in` sama-sama bernilai `true` setelah akun tertaut. Sesi disimpan secara persisten di `storages/`, sehingga penautan ulang tidak diperlukan setelah server dijalankan ulang.

## Logout dan menghapus perangkat

| Tindakan | Endpoint | Dampak |
| - | - | - |
| Logout | `POST /devices/{device_id}/logout` atau `GET /app/logout` | Memutus penautan akun dari WhatsApp dan menghapus sesinya. Slot tetap ada sehingga Anda dapat menautkannya kembali dengan ID yang sama. |
| Hubungkan ulang | `POST /devices/{device_id}/reconnect` atau `GET /app/reconnect` | Membuka kembali koneksi WhatsApp tanpa penautan ulang. |
| Hapus | `DELETE /devices/{device_id}` | Melakukan logout, lalu menghapus slot beserta sesi dan data chat-nya. |

Akun yang penautannya diputus dari ponsel (Perangkat tertaut → Keluar) mengalami logout dengan cara yang sama: slot tetap ada dan perlu ditautkan kembali.

## Daftar periksa keamanan

* Selalu tetapkan `APP_BASIC_AUTH` dengan kata sandi kuat pada layanan apa pun yang dapat diakses melalui jaringan.
* Lakukan terminasi TLS pada reverse proxy; kredensial Basic Auth hanya dienkode dengan base64.
* Batasi `APP_CORS_ALLOWED_ORIGINS` saat antarmuka browser memanggil API.
* Buat `WHATSAPP_WEBHOOK_SECRET` tetap dengan `openssl rand -hex 32`. Secret kosong atau secret contoh yang dipublikasikan akan diganti dengan kunci acak per proses yang berubah saat server dijalankan ulang.
* Perlakukan `storages/` sebagai data sensitif. Direktori ini berisi kunci sesi setiap akun tertaut. Berkas SQLite baru menggunakan izin khusus pemilik, dan direktori yang dibuat untuknya menggunakan `0700`. Lindungi cadangan dengan kehati-hatian yang sama.


## Related topics

- [Autentikasi API](https://gowa-docs.mintlify.site/id/api-reference/authentication.md)
- [Referensi API](https://gowa-docs.mintlify.site/id/api-reference/introduction.md)
- [Mulai Cepat](https://gowa-docs.mintlify.site/id/quickstart.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/id/index.md)
- [Metrik server](https://gowa-docs.mintlify.site/id/api-reference/metrics.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.