- API access: who may call GOWA. This is HTTP Basic Auth.
- WhatsApp pairing: linking a WhatsApp account to a device slot, as you would link WhatsApp Web.
API access: Basic Auth
Basic Auth is the only API authentication method. There are no API keys or JWTs for REST calls. Set one or moreuser:password pairs, comma-separated:
APP_HOST=0.0.0.0, refuses to start without complete credentials. For local development without authentication, bind APP_HOST=127.0.0.1.
If a reverse proxy authenticates every caller, APP_ALLOW_UNAUTHENTICATED=true or --allow-unauthenticated=true explicitly permits a non-loopback listener without Basic Auth. Restrict direct access to that listener.
Send credentials on every request:
401 Unauthorized.
What is not behind Basic Auth
Everything else, including the dashboard at
/, /mcp and /ws, requires Basic Auth when it is configured.
WebSocket
Browsers cannot set headers on WebSocket connections, so/ws takes the credential in the query string:
authorization is base64(user:password). Use TLS (wss://) and redact the query string in proxy logs. The WebSocket checks the browser origin against the same trusted origins used for state-changing HTTP requests. The current WebSocket hub broadcasts events to all connected sockets. A device_id query selects the device context for the connection but does not isolate event delivery. Use the event’s device identifiers to filter the dashboard view, and grant API access only to callers trusted with all devices.
See the WebSocket reference for event codes, payloads, and a client example.
CORS
CORS allows any origin by default. Restrict it withAPP_CORS_ALLOWED_ORIGINS=https://ui.example.com (comma-separated). Allowed request headers are Origin, Content-Type, Accept, Authorization, and X-Device-Id.
CORS and browser origin checks are separate. A wildcard CORS origin does not authorize state-changing requests or WebSockets. GOWA trusts the request’s own host, specific CORS origins, APP_TRUSTED_ORIGINS, and the origins configured for the OAuth issuer and Chatwoot callback URL. For a separate dashboard, configure its exact origin:
403 CROSS_SITE_REQUEST_BLOCKED. This also covers GET routes that log in, log out, reconnect, or reset an invite link. Clients such as curl that send no browser-origin headers continue to work.
A null origin is never trusted. Serve gowa-ui.html over HTTP or HTTPS instead of opening it as a file:// URL. Behind a reverse proxy, preserve Host, configure trusted proxies with X-Forwarded-Host, or list the public origin in APP_TRUSTED_ORIGINS.
WhatsApp pairing
Every WhatsApp account lives in a device slot. Create the slot first, then pair it. Routes under/devices/{device_id} take the device from the path. The equivalent /app/* routes use the X-Device-Id header.
QR code
qr_link and scan it from the phone: Settings → Linked devices → Link a device. Request a new code after qr_duration seconds. The dashboard at / shows the QR directly and updates live over the WebSocket.
Pairing code
results.pair_code, an 8-character code. On the phone, choose Link with phone number instead and type it in. phone must be the number of the account being linked, with country code.
Passkey
If the phone asks for passkey verification during QR login, GOWA stores a WebAuthn challenge and broadcastsPASSKEY_REQUEST on the WebSocket. The dashboard handles this flow. To drive it yourself:
GET /app/passkeyreturns the pending challenge.POST /app/passkey/responsesubmits the WebAuthn assertion (PublicKeyCredential.toJSON()format).- Wait for
PASSKEY_CONFIRMATION. Whenresult.skip_handoff_uxis true, the active QR flow sends the confirmation automatically. Otherwise compareresult.codewith the code on the phone, then callPOST /app/passkey/confirm.
X-Device-Id on all three calls.
Check the result
results.is_connected and results.is_logged_in are both true once the account is linked. Sessions persist in storages/, so restarts do not require pairing again.
Logging out and removing
An account unlinked from the phone (Linked devices → Log out) is logged out the same way: the slot remains and needs pairing again.
Security checklist
- Always set
APP_BASIC_AUTHwith strong passwords on anything reachable from a network. - Terminate TLS at a reverse proxy; Basic Auth credentials are only base64-encoded.
- Restrict
APP_CORS_ALLOWED_ORIGINSwhen a browser UI calls the API. - Generate a stable
WHATSAPP_WEBHOOK_SECRETwithopenssl rand -hex 32. Empty or published example secrets are replaced with a random per-process key that changes on restart. - Treat
storages/as sensitive. It contains every linked account’s session keys. New SQLite files use owner-only permissions, and directories created for them use0700. Protect backups with the same care.
