Skip to main content
GOWA supports HTTP Basic Auth and nothing else: there are no API keys, bearer tokens or JWTs for the REST API. (MCP can additionally accept OAuth tokens; see MCP server.)

Configure

Each comma-separated user:pass pair is a valid login. Every entry must contain both a username and password. A non-loopback listener refuses to start without complete credentials. Bind APP_HOST=127.0.0.1 for unauthenticated local development. Use APP_ALLOW_UNAUTHENTICATED=true only when a reverse proxy authenticates callers and direct access to GOWA is restricted.

Send credentials

Wrong or missing credentials return 401 Unauthorized.

Public routes

WebSocket

Browsers cannot set headers on WebSocket connections, so /ws also accepts /ws?device_id=my-device&authorization=<base64 user:pass>. Use wss:// and redact credentials from proxy logs. The WebSocket and state-changing HTTP routes reject untrusted browser origins. Set the dashboard’s exact origin in APP_TRUSTED_ORIGINS or APP_CORS_ALLOWED_ORIGINS. A wildcard CORS origin does not grant this access, and null origins from file:// pages are rejected. HTTP mutations from an untrusted origin return 403 CROSS_SITE_REQUEST_BLOCKED. See browser access configuration.

Device header

Basic Auth identifies the API caller, not the WhatsApp account. Every device-scoped call also needs X-Device-Id when more than one device exists. See Multi-device.
Basic Auth sends credentials on every request. Always use HTTPS in front of GOWA outside a trusted network.