> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 设置 API Key 网络访问策略

设置或更新单个 API Key 的网络访问策略。采用全量覆盖：提交后该 Key 允许的 IP 即为本次提交的内容。若需新增一个 IP，请先查询现有列表，再连同新 IP 一起提交。

<Info>
  网络访问策略仅作用于模型调用接口，不影响本组网络访问读写接口本身。即使配置的 IP 不包含当前请求来源，你仍可调用本接口或清除接口改回，不会把自己锁死。
</Info>

## 权限

| 角色            | 是否可设置                     |
| :------------ | :------------------------ |
| Owner / Admin | 可设置团队内任意 API Key 的网络访问策略。 |
| Developer     | 只能设置自己创建的 API Key。        |
| 基础用户          | 不可设置。                     |
| 财务管理员         | 不可设置。                     |

被设置的 API Key 必须属于当前调用方所在的团队。设置无权限或不属于本团队的 Key 时，接口不会暴露目标 Key 是否存在，一律按无权限处理。

## 请求头

<ParamField header="Content-Type" type="string" required={true}>
  枚举值：`application/json`
</ParamField>

<ParamField header="Authorization" type="string" required={true}>
  Bearer 身份验证格式，例如：Bearer \{\{API 密钥}}。
</ParamField>

## 路径参数

<ParamField path="stringId" type="string" required={true}>
  目标 API Key 的 stringId。
</ParamField>

## 请求体

<ParamField body="allowedIps" type="string[]" required={true}>
  允许的来源 IP 列表，最多 100 条。每项为 IPv4 地址（如 `203.0.113.5`）或 IPv4 CIDR 网段（如 `198.51.100.0/24`）。传空数组表示不限制来源 IP。
</ParamField>

<Note>
  写入校验：

  * 每一项必须是合法的 IPv4 地址或 IPv4 CIDR 网段；IPv6、域名、通配符一律拒绝。
  * 拒绝 `0.0.0.0/0`（全零网段）；「不限制来源」用空数组表达。
  * 条目总数超过 100 条时拒绝。
  * 重复条目服务端自动去重，最终以规范化后的结果为准。
  * 任一条不通过则整次请求失败，不做部分写入。校验失败返回 HTTP 400，`message` 区分具体原因（格式非法 / 超出条数上限 / 全零网段）。
</Note>

## 响应

返回结构与<a href="/docs/management/reference-key-get-ip-access-policy">查询 API Key 网络访问策略</a>一致，为规范化后的最新策略对象。

<RequestExample>
  ```bash theme={null}
  curl --request PUT \
    --url https://api.ppio.com/openapi/v2/user/key/<stringId>/ip-access-policy \
    --header 'Authorization: Bearer <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "allowedIps": ["203.0.113.5", "198.51.100.0/24"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "stringId": "key_xxx",
    "policy": {
      "allowedIps": ["203.0.113.5", "198.51.100.0/24"]
    },
    "policyStatus": "active",
    "allowedIpCount": 2,
    "updatedAt": "2026-08-13T10:25:12Z",
    "updatedBy": "a3f1c9e2-5b7d-4e81-9c34-2f6a8d0b1e57"
  }
  ```
</ResponseExample>