Skip to main content
GOWA has two separate kinds of authentication:
  1. API access: who may call GOWA. This is HTTP Basic Auth.
  2. 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 more user:password pairs, comma-separated:
Every entry must contain a nonempty username and password. The default listener, 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:
A missing or wrong credential returns 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 with APP_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:
An untrusted browser mutation returns 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

Open 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

The response contains 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 broadcasts PASSKEY_REQUEST on the WebSocket. The dashboard handles this flow. To drive it yourself:
  1. GET /app/passkey returns the pending challenge.
  2. POST /app/passkey/response submits the WebAuthn assertion (PublicKeyCredential.toJSON() format).
  3. Wait for PASSKEY_CONFIRMATION. When result.skip_handoff_ux is true, the active QR flow sends the confirmation automatically. Otherwise compare result.code with the code on the phone, then call POST /app/passkey/confirm.
Send 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_AUTH with 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_ORIGINS when a browser UI calls the API.
  • Generate a stable WHATSAPP_WEBHOOK_SECRET with openssl 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 use 0700. Protect backups with the same care.