> ## 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 认证

> GOWA 只用 HTTP Basic Auth 认证API。

GOWA 支持 **HTTP Basic Auth** ，没有其他：REST API 没有API的 API 密钥、无记名令牌或 JWT。 (MCP 可以另外接受 OAuth 令牌；查看 [MCP 服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md#%E4%BD%BF%E7%94%A8-oauth-%E7%9A%84%E8%BF%9C%E7%A8%8B%E5%AE%A2%E6%88%B7%E7%AB%AF).)

## 配置

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

每个逗号分隔的 `user:pass` 对是一个有效的登录。每个条目都必须包含一个用户名和密码。 非循环监听器拒绝在没有完整凭据的情况下开始。 绑定`APP_HOST=127.0.0.1` 用于未经认证的本地开发。只有当逆向代理认证呼叫者和直接访问 GOWA时，才使用 `APP_ALLOW_UNAUTHENTICATED=true` 。

## 发送凭据

```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"})
```

凭据错误或缺失时返回 `401 Unauthorized`。

## 公共路由

| 路由 | 为什么原因 |
| - | - |
| `/health` | 忠诚度检查。 |
| `/statics/*` | QR 图像和媒体文件。已知URL仍然是公开的。非图像上传下载作为附件。如果需要，请在您的代理上保护访问。 |
| `/chatwoot/webhook`、`/chatwoot/webhook/{device_id}` | 由 Chatwoot 调用；由 `CHATWOOT_WEBHOOK_SECRET` 保护。 |
| MCP OAuth 端点和 `/.well-known/*` 元数据 | 启用时OAuth flow。 |

## WebSocket

浏览器无法在 WebSocket 连接上设置头部，所以`/ws` 也接受`/ws?device_id=my-device&authorization=<base64 user:pass>`。使用 `wss://` 并编辑代理日志的凭据。

WebSocket 和 state-changing HTTP 路由拒绝不信任的浏览器来源。请在 `APP_TRUSTED_ORIGINS` 或 `APP_CORS_ALLOWED_ORIGINS` 中设置仪表板的确切来源。 通配符 CORS 源不授予此访问权限，拒绝了 `file://` 中的 `null` 起源。 HTTP 突变来自一个不信任的源返回 `403 CROSS_SITE_REQUEST_BLOCKED`。请参阅[浏览器访问配置](https://gowa-docs.mintlify.site/zh/authentication.md#cors)。

## 设备头

基本身份验证标识了 API 呼叫器，而不是 WhatsApp 帐户。 当存在多个设备时，每个设备范围内的调用也需要 `X-Device-Id` 。请参阅 [Multi-device](https://gowa-docs.mintlify.site/zh/concepts/multidevice.md)。

> [!WARNING]
>
> 基本认证每个请求都发送凭据。通常会在 GOWA 之前在信任网络之外使用HTTPS。


## Related topics

- [认证](https://gowa-docs.mintlify.site/zh/authentication.md)
- [API 参考](https://gowa-docs.mintlify.site/zh/api-reference/introduction.md)
- [快速开始](https://gowa-docs.mintlify.site/zh/quickstart.md)
- [用户我的列表组](https://gowa-docs.mintlify.site/zh/api-reference/user/用户我的列表组.md)
- [WebSocket 事件](https://gowa-docs.mintlify.site/zh/api-reference/websocket.md)


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