# API IP 白名单

本文将介绍小程序、小游戏、公众号、服务号、微信小店、小店带货助手、第三方平台、视频号助手、联盟带货机构的 API IP 白名单配置方法。

注意：当前微信生态内多个业务需配置 API IP 白名单，详细的规则参考下文，每个业务均有细微区别。

## 1、小程序与小游戏 IP 白名单

在小程序/小游戏业务中，分别有「API IP 白名单」和「代码上传 IP 白名单」两个配置，说明如下：

- **API IP 白名单**：开启后只有白名单内的 IP 才可以调用参数为 `AppSecret` 的接口，如[获取接口调用凭据](/miniprogram/dev/server/API/mp-access-token/api_getaccesstoken.md)、[获取稳定版接口调用凭据](/miniprogram/dev/server/API/mp-access-token/api_getstableaccesstoken.md)以及[使用 AppSecret 重置 API 调用次数](/miniprogram/dev/server/API/openApi-mgnt/api_clearquotabyappsecret.md)这三个接口。
- **代码上传 IP 白名单**：白名单内的 IP 才可成功调用代码上传接口，具体会影响 [miniprogram-ci](/miniprogram/dev/devtools/ci.md) 的使用。

**操作路径**

- 添加「API IP 白名单」路径为：[微信公众平台](https://mp.weixin.qq.com) - 开发管理 - 开发设置 - 开发者 ID - IP 白名单
- 添加「代码上传 IP 白名单」路径为：[微信公众平台](https://mp.weixin.qq.com) - 开发管理 - 开发设置 - 小程序代码上传 - IP 白名单

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F20250629202753989.png)

**配置规则**

API IP 白名单：

1）一个小程序/小游戏支持配置 10 个 API IP 白名单

2）支持具体 IP 以及 IP 段，如 `172.0.0.1`、`172.0.0.*`、`172.0.0.1/24`

3）不支持「IP:端口」形式

![](https://res8.wxqcloud.qq.com.cn/wxdoc/b0bd5049-8bd7-43d3-a292-f5c09f915df3.png)

代码上传 IP 白名单：

1）一个小程序/小游戏支持配置 10 个代码上传 IP 白名单

2）支持具体 IP 以及 IP 段，如 `172.0.0.1`、`172.0.0.*`、`172.0.0.1/24`

3）不支持「IP:端口」形式

**影响与后果**

- 如果配置了 API IP 白名单，但不在白名单内调用参数为 `AppSecret` 的接口，则返回 `40164` 的报错，如 `{"errcode":40164,"errmsg":"invalid ip 8.149.XXX.108 ipv6 ::ffff:8.149.XXX.108, not in whitelist rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}`
- 出现该问题，只需将 IP 添加至「API IP 白名单」即可

## 2、公众号与服务号 IP 白名单

公众号与服务号也支持「API IP 白名单」配置，具体说明以及配置规则如下：

- **API IP 白名单**：仅白名单中的 IP 才可调用公众号/服务号的服务端接口，即通过 `AppSecret` 或者 `access_token` 调用服务端接口时，需将访问来源 IP 设置为 IP 白名单。
- 配置规则：支持具体 IP 以及 IP 段，如 `172.0.0.1`、`172.0.0.1/24`（不支持 `172.0.0.*` 这种格式）
- 可支持配置多个
- 不支持「IP:端口」形式

**操作路径**

- [微信开发者平台](https://developers.weixin.qq.com/platform/) - 我的业务 - 公众号/服务号 - 基础信息 - 开发信息

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F20250629202257216.png)

**影响与后果**

- 如果配置了 API IP 白名单，但不在白名单内调用服务端接口，则返回 `40164` 的报错，如 `{"errcode":40164,"errmsg":"invalid ip 8.149.XXX.108 ipv6 ::ffff:8.149.XXX.108, not in whitelist rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}`
- 出现该问题，只需将 IP 添加至「API IP 白名单」即可

## 3、小店带货助手 IP 白名单

小店带货助手也支持「API IP 白名单」配置，具体说明以及配置规则如下：

- **API IP 白名单**：开启后只有白名单内的 IP 才可以调用参数为 `AppSecret` 的接口。
- 若删除所有的 IP，则默认关闭 IP 白名单。设置成功后十分钟生效。
- 配置规则：支持具体 IP 以及 IP 段，如 `172.0.0.1`、`172.0.0.1/24`（不支持 `172.0.0.*` 这种格式）
- 可支持配置多个
- 不支持「IP:端口」形式

**操作路径**

- [微信开发者平台](https://developers.weixin.qq.com/platform/) - 我的业务 - 带货助手 - 基础信息 - 开发信息

![](https://res8.wxqcloud.qq.com.cn/wxdoc/951bb16e-dc2b-4f78-8dd1-79621da748bd.png)

**影响与后果**

- 如果配置了 API IP 白名单，但不在白名单内调用参数为 `AppSecret` 的接口，则返回 `40164` 的报错，如 `{"errcode":40164,"errmsg":"invalid ip 8.149.XXX.108 ipv6 ::ffff:8.149.XXX.108, not in whitelist rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}`
- 出现该问题，只需将 IP 添加至「API IP 白名单」即可

## 4、微信小店 IP 白名单

微信小店也支持「API IP 白名单」配置，具体说明以及配置规则如下：

- **API IP 白名单**：开启后只有白名单内的 IP 才可以调用参数为 `AppSecret` 的接口。
- 若删除所有的 IP，则默认关闭 IP 白名单。设置成功后十分钟生效。
- 配置规则：支持具体 IP 以及 IP 段，如 `172.0.0.1`、`172.0.0.1/24`
- IP 段仅支持 /8、/16、/24 网段，不支持其他网段
- 不支持「IP:端口」形式
- 最多可支持配置 200 个

**操作路径**

- [微信小店](https://store.weixin.qq.com/shop/home) - 服务市场 - 经营工具 - 自研

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F20250629202957532.png)

**影响与后果**

- 如果配置了 API IP 白名单，但不在白名单内调用参数为 `AppSecret` 的接口，则返回 `40164` 的报错，如 `{"errcode":40164,"errmsg":"invalid ip 8.149.XXX.108 ipv6 ::ffff:8.149.XXX.108, not in whitelist rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}`
- 出现该问题，只需将 IP 添加至「API IP 白名单」即可

## 5、视频号助手 IP 白名单

视频号助手也支持「API IP 白名单」配置，具体说明以及配置规则如下：

- **API IP 白名单**：开启后只有白名单内的 IP 才可以调用参数为 `AppSecret` 的接口。
- 若删除所有的 IP，则默认关闭 IP 白名单。设置成功后十分钟生效。
- 配置规则：支持具体 IP 以及 IP 段，如 `172.0.0.1`、`172.0.0.1/24`
- IP 段仅支持 /8、/16、/24 网段，不支持其他网段
- 不支持「IP:端口」形式
- 最多可支持配置 200 个

**操作路径**

- [视频号助手](https://channels.weixin.qq.com/) - 直播 - 直播管理 - 开放能力 - 基础信息

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F20250629202641669.png)

**影响与后果**

- 如果配置了 API IP 白名单，但不在白名单内调用参数为 `AppSecret` 的接口，则返回 `40164` 的报错，如 `{"errcode":40164,"errmsg":"invalid ip 8.149.XXX.108 ipv6 ::ffff:8.149.XXX.108, not in whitelist rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}`
- 出现该问题，只需将 IP 添加至「API IP 白名单」即可

## 6、第三方平台 IP 白名单

第三方平台也支持「API IP 白名单」配置，具体说明以及配置规则如下：

- **API IP 白名单**：仅白名单中的 IP 才可调用第三方平台的服务端接口，即通过 `component_secret`、`component_access_token` 或者 `authorizer_access_token` 调用服务端接口时，需将访问来源 IP 设置为 IP 白名单。
- 配置规则：仅支持具体 IP，如 `172.0.0.1`（不支持 `172.0.0.*` 以及 `172.0.0.1/24` 这种格式）
- 最多可支持配置 100 个
- 不支持「IP:端口」形式

**操作路径**

- [微信开放平台](https://open.weixin.qq.com) - 管理中心 - 第三方平台 - 详情 - 开发配置 - 开发资料

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F20250629202012653.png)

**影响与后果**

- 如果配置了 API IP 白名单，但不在白名单内调用服务端接口，则返回 `61004` 的报错，如 `{"errcode":61004,"errmsg":"access clientip is not registered requestIP: 119.147.XX.170 rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"}`
- 出现该问题，只需将 IP 添加至「API IP 白名单」即可

## 7、其他业务说明

移动应用、网站应用、多端应用等业务尚未支持配置 IP 白名单，后续会持续完善。