API Authentication

GOWA authenticates API calls with HTTP Basic Auth only.

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

APP_BASIC_AUTH=admin:changeme,ops:another-password   # or --basic-auth=admin:changeme

Each comma-separated user:pass pair is a valid login. A malformed entry stops startup. If APP_BASIC_AUTH is empty, the API is open to anyone who can reach it.

Send credentials

curl

curl -u admin:changeme -H "X-Device-Id: my-device" \
  http://localhost:3000/app/devices

Wrong or missing credentials return 401 Unauthorized.

Public routes

Route	Why
/health	Liveness checks.
/statics/*	QR images and media files. Protect at your proxy if needed.
/chatwoot/webhook, /chatwoot/webhook/{device_id}	Called by Chatwoot; secured by CHATWOOT_WEBHOOK_SECRET.
MCP OAuth endpoints and /.well-known/* metadata	OAuth flow, when enabled.

WebSocket

Browsers cannot set headers on WebSocket connections, so /ws also accepts the credentials as a query parameter: /ws?device_id=my-device&authorization=<base64 user:pass>.

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.