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

# Authentication

> Protect the API with Basic Auth, then pair each WhatsApp account by QR code, pairing code or passkey.

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:

```bash theme={null}
# environment
APP_BASIC_AUTH=admin:changeme,ops:another-secret
# or flag
./whatsapp rest --basic-auth=admin:changeme,ops:another-secret
```

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:

```bash theme={null}
curl -u admin:changeme http://localhost:3000/app/info
# same as
curl -H "Authorization: Basic YWRtaW46Y2hhbmdlbWU=" http://localhost:3000/app/info
```

A missing or wrong credential returns `401 Unauthorized`.

### What is not behind Basic Auth

| Route | Why |
| - | - |
| `GET /health` | Liveness probe. Always at the root, ignoring `APP_BASE_PATH`. |
| `POST /chatwoot/webhook`, `POST /chatwoot/webhook/{device_id}` | Called by Chatwoot. Registered only when `CHATWOOT_ENABLED=true` and protected by `CHATWOOT_WEBHOOK_SECRET` instead. See [Chatwoot](https://gowa-docs.mintlify.site/integrations/chatwoot.md). |
| MCP OAuth discovery and `/oauth/*` endpoints | Only when `MCP_OAUTH_ENABLED=true`. See [MCP server](https://gowa-docs.mintlify.site/integrations/mcp.md). |
| `GET /statics/*` | QR images, uploads, and downloaded media. Served before Basic Auth. Anyone who knows a file URL can retrieve it. Only validated JPEG, PNG, GIF, and WebP files in image paths display inline. Other files download as attachments with a non-active content type and `X-Content-Type-Options: nosniff`. Restrict file access at the proxy when required. |

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:

```text theme={null}
ws://localhost:3000/ws?device_id=my-device&authorization=YWRtaW46Y2hhbmdlbWU=
```

`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](https://gowa-docs.mintlify.site/api-reference/websocket.md) 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:

```env theme={null}
APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
APP_TRUSTED_ORIGINS=https://ui.example.com
```

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.

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/devices \
  -H "Content-Type: application/json" -d '{"device_id": "sales"}'
```

### QR code

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/login
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Login success",
  "results": {
    "device_id": "sales",
    "qr_link": "http://localhost:3000/statics/qrcode/scan-qr-b0b7bb43-....png",
    "qr_duration": 30
  }
}
```

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

```bash theme={null}
curl -u admin:changeme -X POST \
  "http://localhost:3000/devices/sales/login/code?phone=628123456789"
```

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

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/status
```

`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

| Action | Endpoint | Effect |
| - | - | - |
| Log out | `POST /devices/{device_id}/logout` or `GET /app/logout` | Unlinks the account from WhatsApp and clears its session. The slot stays, so you can pair it again under the same ID. |
| Reconnect | `POST /devices/{device_id}/reconnect` or `GET /app/reconnect` | Reopens the WhatsApp connection without pairing again. |
| Remove | `DELETE /devices/{device_id}` | Logs out, then deletes the slot together with its session and chat data. |

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.


## Related topics

- [API Authentication](https://gowa-docs.mintlify.site/api-reference/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.