> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://gowa-docs.mintlify.site/integrations/mcp.md#remote-clients-with-oauth).)

## Configure

```bash theme={null}
APP_BASIC_AUTH=admin:changeme,ops:another-password   # or --basic-auth=admin:changeme
```

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

```bash curl theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  http://localhost:3000/app/devices
```

```bash Header theme={null}
curl -H "Authorization: Basic $(echo -n 'admin:changeme' | base64)" \
  -H "X-Device-Id: my-device" \
  http://localhost:3000/app/devices
```

```javascript JavaScript theme={null}
const res = await fetch("http://localhost:3000/user/my/groups", {
  headers: {
    Authorization: "Basic " + Buffer.from("admin:changeme").toString("base64"),
    "X-Device-Id": "my-device",
  },
});
```

```python Python theme={null}
import requests
r = requests.get("http://localhost:3000/user/my/groups",
                 auth=("admin", "changeme"),
                 headers={"X-Device-Id": "my-device"})
```

Wrong or missing credentials return `401 Unauthorized`.

## Public routes

| Route | Why |
| - | - |
| `/health` | Liveness checks. |
| `/statics/*` | QR images and media files. Known URLs remain public. Non-image uploads download as attachments. Protect access 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 `/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](https://gowa-docs.mintlify.site/authentication.md#cors).

## 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](https://gowa-docs.mintlify.site/concepts/multidevice.md).

> [!WARNING]
>
> Basic Auth sends credentials on every request. Always use HTTPS in front of GOWA outside a trusted network.


## Related topics

- [Authentication](https://gowa-docs.mintlify.site/authentication.md)
- [API Reference](https://gowa-docs.mintlify.site/api-reference/introduction.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/index.md)
- [Server metrics](https://gowa-docs.mintlify.site/api-reference/metrics.md)
- [Quickstart](https://gowa-docs.mintlify.site/quickstart.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.