Langsung ke konten utama
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:
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:
Kredensial yang tidak disertakan atau salah menghasilkan 401 Unauthorized.

Rute yang tidak dilindungi Basic Auth

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:
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 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:
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.

Kode QR

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

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

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

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.