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

# 认证

> 使用 Basic Auth 保护API，然后通过QR 代码配对每一个 WhatsApp 帐户，配对代码或密码。

妇女事务局有两种单独的认证类型：

1. **API 访问**：谁可以调用 GOWA。这是HTTP Basic Auth。
2. **WhatsApp 配对**: 将 WhatsApp 帐户链接到设备栏位, 因为你会链接WhatsApp Web.

## API 访问：基本认证

基本认证是唯一的 API 认证方法。没有用于REST 调用的 API 密钥或JWT。

设置一个或多个`user:password`对，逗号分隔：

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

每个条目都必须包含非空的用户名和密码。默认监听地址 `APP_HOST=0.0.0.0` 在凭据不完整时会拒绝启动。如需在本地开发时不使用认证，请绑定 `APP_HOST=127.0.0.1`。

如果逆向代理认证每个来电者，`APP_ALLOW_UNAUTHENTICATED=true` 或 `--allow-unauthenticated=true` 明确允许一个非循环回音监听器而无需基本认证。限制直接访问该监听器。

每次请求时发送凭据：

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

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

### 基本认证后面没有的内容

| 路由 | 为什么原因 |
| - | - |
| `GET /health` | 真理探测。总是根目录，忽略`APP_BASE_PATH`。 |
| `POST /chatwoot/webhook`、`POST /chatwoot/webhook/{device_id}` | 由 Chatwoot 调用。仅在 `CHATWOOT_ENABLED=true` 时注册，并改用 `CHATWOOT_WEBHOOK_SECRET` 进行保护。参见 [Chatwoot](https://gowa-docs.mintlify.site/zh/integrations/chatwoot.md)。 |
| MCP OAuth 发现和 `/oauth/*` 终点 | 仅当`MCP_OAUTH_ENABLED=true`时。请参阅[MCP服务器](https://gowa-docs.mintlify.site/zh/integrations/mcp.md)。 |
| `GET /statics/*` | 二维码图像、上传文件和下载的媒体。这些文件在 Basic Auth 认证之前提供，任何知道文件 URL 的人都可以获取。只有图像路径中经过验证的 JPEG、PNG、GIF 和 WebP 文件会内联显示。其他文件以附件形式下载，并使用不会执行活动内容的内容类型及 `X-Content-Type-Options: nosniff`。必要时请在代理层限制文件访问。 |

其它一切，包括`/`、`/mcp`和`/ws`的仪表盘，配置时需要基本验证。

### WebSocket

浏览器无法在 WebSocket 连接中设置头部，所以`/ws` 获取查询字符串中的凭据：

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

`authorization` 是 `base64(user:password)` 。使用 TLS (`wss://`) 并编辑代理日志中的查询字符串。 WebSocket 检查浏览器源与更换状态的 HTTP 请求所使用的相同的信任来源。 当前的 WebSocket 枢纽向所有已连接的套接字播放事件。 一个`device_id`查询选择设备连接环境，但不隔离事件交付。 使用事件的设备标识符来过滤仪表盘视图，并且只授予所有设备信任的呼叫者API访问。

查看[WebSocket 引用](https://gowa-docs.mintlify.site/zh/api-reference/websocket.md) 事件代码、有效载荷和客户端示例。

### CORS

CORS 默认允许任何来源。使用 `APP_CORS_ALLOWED_ORIGINS=https://ui.example.com` 进行限制（多个来源以逗号分隔）。允许的请求头为 `Origin`、`Content-Type`、`Accept`、`Authorization` 和 `X-Device-Id`。

CORS 与浏览器来源检查彼此独立。通配符 CORS 来源不会授权更改状态的请求或 WebSocket 连接。GOWA 信任请求自身的主机、明确指定的 CORS 来源、`APP_TRUSTED_ORIGINS`，以及为 OAuth 签发者和 Chatwoot 回调 URL 配置的来源。对于单独部署的仪表板，请配置其确切来源：

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

不可信的浏览器突变返回 `403 CROSS_SITE_REQUEST_BLOCKED`。这也包括登入、注销、重新连接或重置邀请链接的 GET 路由。 客户端，例如无需发送浏览器源头的curl，仍在继续工作。

`null` 来源永远不会被信任。通过 HTTP 或 HTTPS 提供`gowa-ui.html` 而不是以 `file://` 方式打开它。 在逆向代理后面，保留`Host`，使用`X-Forwarded-Host`配置信任代理，或在`APP_TRUSTED_ORIGINS`中列出公共来源。

## WhatsApp 配对

每个 WhatsApp 账号都位于一个**设备槽位**中。请先创建槽位，再进行配对。`/devices/{device_id}` 下的路由通过路径指定设备。对应的 `/app/*` 路由使用 `X-Device-Id` 请求头。

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

打开 `qr_link` 并从手机扫描它：**设置 -> 链接设备 -> 链接设备**。 在 `qr_duration` 秒后请求一个新代码。在 `/` 中的仪表板直接显示QR 并通过 WebSocket 实时更新。

### Pairing code

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

响应包含 `results.pair_code` ，一个8个字符的代码。在手机上选择 **链接电话号码** 然后键入。 `phone` 必须是被链接的帐户号码，带有国家代码。

### 密码

如果在QR登录期间电话请求验证密码，GOWA将在 WebSocket 上存储一个 WebAuthn 挑战和广播 `PASSKEY_REQUEST` 。 仪表盘处理这个流程。要自行驱动它：

1. `GET /app/passkey` 返回待处理的挑战。
2. `POST /app/passkey/response` 提交了 WebAuthn 断言(`PublicKeyCredential.toJSON()` 格式)。
3. 等待`PASSKEY_CONFIRMATION` 。当`result.skip_handoff_ux` 为真时，活动的 QR 流会自动发送确认。 否则将 `result.code` 与手机上的代码比较起来，然后调用 `POST /app/passkey/confirm`。

在所有三次通话时发送 `X-Device-Id` 。

### 检查结果

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

`results.is_connected` 和 `results.is_logged_in` 都是`true`。会话持续在 `storages/` 中，所以重新启动不需要配对。

## 登出并移除

| 行 动 | Endpoint | 效果 |
| - | - | - |
| 注销 | `POST /devices/{device_id}/logout` 或 `GET /app/logout` | 从 WhatsApp 取消链接帐户并清除它的会话。此插槽保持不变，您可以在同一ID下重新配对。 |
| 重新连接 | `POST /devices/{device_id}/reconnect` 或 `GET /app/reconnect` | 重新打开 WhatsApp 连接而不再配对。 |
| 删除 | `DELETE /devices/{device_id}` | 注销，然后删除栏位连同会话和聊天数据。 |

从手机上取消链接的帐户(链接设备-> 注销)将以同样的方式注销：该帐户仍然保留并需要重新配对。

## 安全清单

* 对于任何可通过网络访问的部署，务必设置 `APP_BASIC_AUTH` 并使用强密码。
* 在逆向代理中终止TLS; 基本认证凭据仅为 base64 编码。
* 当浏览器UI调用API时，限制`APP_CORS_ALLOWED_ORIGINS` 。
* 生成一个稳定的 `WHATSAPP_WEBHOOK_SECRET` 与 `openssl rand -hex 32` 。空或已发布的示例密钥被替换为每个进程的随机密钥，在重启时会更改。
* 将 `storages/` 视为敏感数据。它包含每个已关联账户的会话密钥。新建的 SQLite 文件仅允许所有者访问，为其创建的目录使用 `0700` 权限。请同样谨慎地保护备份。


## Related topics

- [API 认证](https://gowa-docs.mintlify.site/zh/api-reference/authentication.md)
- [API 参考](https://gowa-docs.mintlify.site/zh/api-reference/introduction.md)
- [正在发送消息](https://gowa-docs.mintlify.site/zh/examples/sending-messages.md)
- [安装](https://gowa-docs.mintlify.site/zh/installation.md)
- [快速开始](https://gowa-docs.mintlify.site/zh/quickstart.md)


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