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

# 设置 API Key 网络访问策略

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

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

## 权限

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

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

## 请求头

**Content-Type** `string` *required*

枚举值：`application/json`

**Authorization** `string` *required*

Bearer 身份验证格式，例如：Bearer \{\{API 密钥}}。

## 路径参数

**stringId** `string` *required*

目标 API Key 的 stringId。

## 请求体

**allowedIps** `string[]` *required*

允许的来源 IP 列表，最多 100 条。每项为 IPv4 地址（如 `203.0.113.5`）或 IPv4 CIDR 网段（如 `198.51.100.0/24`）。传空数组表示不限制来源 IP。

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

## 响应

返回结构与[查询 API Key 网络访问策略](https://docs.jiekou.ai/docs/models/reference-key-get-ip-access-policy.md)一致，为规范化后的最新策略对象。

```bash theme={null}
curl --request PUT \
  --url https://api.highwayapi.ai/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"]
  }'
```

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


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