> ## 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. A malformed entry stops startup. If `APP_BASIC_AUTH` is empty, the API is open to anyone who can reach it.

## 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. 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](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.


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