通过Postman配置启用WhatsApp Business API遇401 Unauthorized错误的求助

基础匹配性排查 #

• 核对容器实际端口映射：执行docker ps查询WhatsApp Business API相关容器的端口映射记录，确认外部可访问的HTTPS端口与Postman配置的访问URL端口完全一致，避免端口映射写错、端口占用导致的请求被拒绝。注：当前版本单实例API的认证服务默认监听内部9090端口，旧版的7901端口已无对应监听器，直接使用7901发请求本身就会触发异常。
• 校验请求协议匹配：认证服务默认使用自签名HTTPS协议，需要在Postman设置中关闭SSL证书校验，不要用HTTP协议访问对应端口，协议不匹配会被直接拦截返回401。

认证凭据校验 #

• 确认管理员用户名密码与服务初始化配置完全一致：AdminUsername默认固定为admin，AdminPassword必须填写服务初始化时在docker-compose配置里设置的管理员密码，不要直接沿用官方示例里的默认值secret，凭据不匹配是触发401的最常见原因。
• 注意NewAdminPassword变量的使用场景：该值仅在首次调用管理员密码修改接口时需要填写，后续所有请求的认证头只需要使用更新后的管理员密码，不要混用新老两套凭据。
• 检查请求路径配置：Postman Collection的全局根URL只需要填写协议+地址+端口，不要手动拼接/api等路径后缀，Collection内的接口会自动拼接对应路径，路径不匹配会被网关拦截返回401。

服务状态与日志排查 #

• 等待服务完全初始化后再发请求：单实例API的认证服务启动需要3-5分钟，刚完成docker-compose up就发起请求时，服务尚未完成初始化，也会返回401；可以查看导出的日志，等出现认证服务启动完成的标识字段后再开展测试。
• 在导出的debug_output.txt日志中检索authentication failed关键字，401错误会直接在日志中记录具体诱因（凭据错误、请求IP不在白名单等），无需逐行逐段排查全量日志。

环境隔离说明 #

本地安装的MySQL Workbench连接的是宿主机本地的MySQL服务，而WhatsApp Business API单实例自带的数据库运行在独立的docker网络中，默认与宿主机本地环境完全隔离，该配置与当前遇到的401问题无关联，不需要作为优先排查项。

内容的提问来源于stack exchange，提问作者Zjost