GOWA provides two layers of authentication: WhatsApp login (connecting your phone number) and API authentication (securing HTTP endpoints).
WhatsApp authentication
QR code login
Scan a QR code with your WhatsApp mobile app to link a device.
Generate QR code
Request a QR code for device login:curl http://localhost:3000/devices/my-device/login
{
"code": 200,
"message": "Success",
"data": {
"qr_code": "data:image/png;base64,iVBORw0KGgoAAAANS...",
"qr_duration": 60
}
}
Scan QR code
On your phone:
- Open WhatsApp
- Tap Menu (⋮) or Settings
- Select Linked Devices
- Tap Link a Device
- Scan the QR code displayed in browser or API response
Connection established
After successful scan:
- Device state changes to
connected
- Session keys stored in
storages/{jid}/session.db
- Device appears in your phone’s “Linked Devices” list
QR codes expire after 60 seconds. Request a new QR if expired.
Pairing code login
Link device using an 8-digit pairing code (no QR scanning required).
Request pairing code
curl -X POST http://localhost:3000/devices/my-device/login/code \
-H "Content-Type: application/json" \
-d '{"phone": "628123456789"}'
{
"code": 200,
"message": "Success",
"data": {
"code": "ABCD-1234",
"duration": 60
}
}
Enter code on phone
On your phone:
- Open WhatsApp
- Tap Menu → Linked Devices → Link a Device
- Tap Link with phone number instead
- Enter the 8-digit code (e.g.,
ABCD-1234)
Pairing codes are ideal for headless servers or when QR scanning is impractical.
Which method to use?
| Scenario | Recommended Method |
|---|
| Local development with UI | QR Code |
| Headless server | Pairing Code |
| Automation scripts | Pairing Code |
| Mobile-first setup | QR Code |
Session persistence
After successful login, session data is stored in SQLite:
storages/{jid}/session.db
- Encryption keys (AES-256)
- Device identity certificates
- WhatsApp protocol state
Never share session.db files - they provide full access to your WhatsApp account.
Session lifecycle
- Reconnect: Server restarts automatically restore sessions
- Logout: Explicitly invalidates session and removes from phone
API authentication
Secure your HTTP endpoints with HTTP Basic Authentication.
Enable basic auth
CLI Flag
Environment Variable
Docker
./whatsapp rest --basic-auth="admin:secret123"
export APP_BASIC_AUTH="admin:secret123"
./whatsapp rest
docker run -p 3000:3000 \
-e APP_BASIC_AUTH="admin:secret123" \
aldinokemal2104/go-whatsapp-web-multidevice rest
Multiple credentials
Support multiple users with comma-separated credentials:
--basic-auth="admin:secret,user:pass123,api:token456"
Using authenticated endpoints
curl -u admin:secret123 \
http://localhost:3000/send/message \
-H "Content-Type: application/json" \
-d '{"phone": "[email protected]", "message": "Hello"}'
Error responses
Missing or invalid credentials return:
{
"code": 401,
"message": "Unauthorized",
"data": null
}
Production security
Always use HTTPS in production - Basic auth credentials are transmitted in base64 (easily decoded).
Reverse proxy setup
Recommended production architecture:
Client → HTTPS → Nginx/Caddy → HTTP → GOWA Server
server {
listen 443 ssl;
server_name api.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Trusted proxies
When behind a reverse proxy, configure trusted proxy ranges:
--trusted-proxies="0.0.0.0/0"
APP_TRUSTED_PROXIES=0.0.0.0/0
X-Forwarded-For headers.
Best practices
Rotate credentials
Change API passwords periodically and after employee departures
Use environment variables
Never hardcode credentials in code or commit to version control
HTTPS only
Always terminate TLS at reverse proxy in production
Monitor sessions
Check device status regularly and logout unused devices
Next steps
Device management
Understand device lifecycle and states
Multi-device setup
Manage multiple WhatsApp accounts
Connection API
Login API reference
Configuration
Complete configuration options
