更新API Key

功能介绍

修改接口赋予了管理员对现有API Key进行动态配置与状态调整的能力。随着业务的迭代，API Key的用途或归属可能会发生变化，该接口支持更新密钥的描述信息以及访问权限范围，确保密钥资产与业务需求保持同步。保障安全的同时保留了业务恢复的灵活性。

接口约束：

鉴权：调用本接口需在请求头携带有效IAM token（X-Auth-Token），并具备对应细粒度权限：更新操作应使用modelarts:apiKey:create
租户隔离：接口操作范围由当前 token 所属的Project / Domain 决定，project_id由鉴权上下文自动带入，不支持跨租户操作。
不可修改字段：label、id，请求体中传入会被服务端忽略，保留原值。可修改字段：description、allow_all、ip_whitelist、resident_model_version_whitelist、endpoint_whitelist。

URI

PUT /v2/{project_id}/maas/api-auth/api-keys/{key_id}

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释：项目ID，是华为云中用于标识租户资源的唯一编号，与具体的区域（Region）相关联。在调用华为云API时用于定位资源所属的项目空间。可通过获取项目ID和名称接口获取。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
key_id	是	String	参数解释：API Key ID。可通过查询API Key列表接口获取。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

请求参数

表2 请求Body参数
参数	是否必选	参数类型	描述
id	否	String	参数解释：API Key ID。可通过查询API Key列表接口获取。约束限制：不可被修改。取值范围：不涉及。默认取值：不涉及。
description	否	String	参数解释：API Key的描述信息。最大长度100 字符。约束限制：不涉及。取值范围：不涉及。默认取值：空字符串。
allow_all	是	Boolean	参数解释：是否允许所有IP访问。约束限制：不涉及。取值范围： true：表示不限制IP。 false：限制IP。默认取值：true。
ip_whitelist	否	Array of strings	参数解释：API Key的IP白名单是华为云MaaS（模型即服务）中API Key的一项安全功能，用于限制只有指定IP地址才能使用该API Key调用模型服务，防止API Key泄露后被非法利用。取值示例：单个IP地址(如：192.168.1.1)。 IP地址段范围(如：192.168.1.10-192.168.1.100)。 CIDR网段(如：192.168.10.0/24)。约束限制：数量 ≤ 100；每个IP须为合法IPv4，支持CIDR格式（如 192.168.0.0/24）；不可有重复IP； CIDR掩码须连续合法；当allow_all=true时此项必须为空。 IP校验规则： IP单段数值校验：IPv4的每一个段（Octet）必须是0到255之间的有效十进制整数。 IP格式与子网掩码校验：整体格式必须符合x.x.x.x 或 x.x.x.x/y的正则规范。若包含子网掩码，其数值必须在0到32之间。特殊业务规则：子网掩码的位数必须大于或等于该IP地址转换为32位二进制后最后一个1所在的位置（即掩码不能截断IP的有效标识位）。 3.IP 大小比较规则：比较两个IP时，按从左到右（高位到低位）逐段进行数值比对，以此确定大小关系。 4.IP 范围校验：一个合法的IP范围必须严格包含2个IP，且这两个IP均需通过上述的格式与掩码校验，同时起始IP必须小于或等于结束IP。
resident_model_version_whitelist	否	ResidentModelVersionWhitelist object	参数解释：常驻模型版本白名单，限制可访问的常驻模型版本。取值范围：不涉及。
endpoint_whitelist	否	EndpointWhitelist object	参数解释：自定义接入点白名单，限制可访问的自定义接入点。取值范围：不涉及。

表3 ResidentModelVersionWhitelist
参数	是否必选	参数类型	描述
overall	否	String	参数解释：API Key生效的模型服务范围（包括模型服务以及对应的版本）。约束限制：不涉及。取值范围： all: 表示全部生效。空字符串：表示非全部生效。默认取值：空字符串。
whitelist	否	Array of Whitelist objects	参数解释：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。取值范围：Whitelist对象数组，见下方拆解字段。

表4 Whitelist
参数	是否必选	参数类型	描述
resident_model_id	否	String	参数解释：常驻模型ID。以Chrome浏览器为例，获取常驻模型ID操作如下：在MaaS控制台的“在线推理-预置服务”页面，使用快捷键F12打开开发者工具，选择“Network”页签，搜索“query”，单击以“query?business_type=payment”开头的名称，在“Response”页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，resident_model_id参数值即为常驻模型ID。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。
version_whitelist	否	String	参数解释：该常驻模型允许访问的版本白名单，多个版本以逗号分隔。以Chrome浏览器为例，获取常驻模型版本名称操作如下：在MaaS控制台的“在线推理-预置服务”页面，使用快捷键F12打开开发者工具，选择“Network”页签，搜索“query”，单击以“query?business_type=payment”开头的名称，在“Response”页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，version_list下对应version_name为DeepSeek-V4.1-Flash的那条数据的id即为常驻模型版本值。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表5 EndpointWhitelist
参数	是否必选	参数类型	描述
overall	否	String	参数解释：整体放行策略。约束限制：不涉及。取值范围：“all” 表示放行全部，空字符串表示不启用整体放行。默认取值：空字符串。
whitelist	否	Array of strings	参数解释：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过查询自定义接入点接口获取ID。约束限制：不涉及。

响应参数

状态码：200

表6 响应Body参数
参数	参数类型	描述
id	String	参数解释：API Key的唯一标识ID，系统自动生成。取值范围：不涉及。
api_key	String	参数解释：推理服务生成的原始API Key明文（仅在创建时返回一次）。长度 ≤ 255 的字符串。取值范围：不涉及。
label	String	参数解释：API Key的显示名称，回显请求中的label。取值范围：不涉及。
description	String	参数解释：API Key的描述信息，回显请求中的description。最大长度100字符。取值范围：不涉及。
allow_all	Boolean	参数解释：是否允许所有IP访问。取值范围： true：表示不限制IP。 false ：限制IP。
ip_whitelist	Array of strings	参数解释：IP白名单列表，回显实际生效值。取值范围：不涉及。
resident_model_version_whitelist	ResidentModelVersionWhitelist object	参数解释：常驻模型版本白名单信息，回显请求中的值。取值范围：不涉及。
endpoint_whitelist	EndpointWhitelist object	参数解释：自定义接入点白名单信息，回显请求中的值。取值范围：不涉及。

表7 ResidentModelVersionWhitelist
参数	参数类型	描述
overall	String	参数解释：API Key生效的模型服务范围（包括模型服务以及对应的版本）。取值范围： all: 表示全部生效。空字符串：表示非全部生效。
whitelist	Array of Whitelist objects	参数解释：常驻模型版本白名单列表，逐条指定可访问的常驻模型及其版本。取值范围：Whitelist对象数组，见下方拆解字段。

表8 Whitelist
参数	参数类型	描述
resident_model_id	String	参数解释：常驻模型ID。以Chrome浏览器为例，获取常驻模型ID操作如下：在MaaS控制台的“在线推理-预置服务”页面，使用快捷键F12打开开发者工具，选择“Network”页签，搜索“query”，单击以“query?business_type=payment”开头的名称，在“Response”页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，resident_model_id参数值即为常驻模型ID。取值范围：不涉及。
version_whitelist	String	参数解释：该常驻模型允许访问的版本白名单，多个版本以逗号分隔。以Chrome浏览器为例，获取常驻模型版本名称操作如下：在MaaS控制台的“在线推理-预置服务”页面，使用快捷键F12打开开发者工具，选择“Network”页签，搜索“query”，单击以“query?business_type=payment”开头的名称，在“Response”页签中，按需搜索模型名称，例如搜索DeepSeek-V4.1-Flash，version_list下对应version_name为DeepSeek-V4.1-Flash的那条数据的id即为常驻模型版本值。取值范围：不涉及。

表9 EndpointWhitelist
参数	参数类型	描述
overall	String	参数解释：整体放行策略。取值范围：“all” 表示放行全部，空字符串表示不启用整体放行。
whitelist	Array of strings	参数解释：自定义接入点ID白名单列表，仅允许列表内的自定义接入点被访问。可通过查询自定义接入点接口获取ID。

状态码：403

**表10** 响应Body参数
参数	参数类型	描述
error_msg	String	参数解释：错误信息描述。取值范围：不涉及。
error_code	String	参数解释：错误码。取值范围：不涉及。

请求示例

权限范围不限制

PUT https://{endpoint}/v2/{project_id}/maas/api-auth/api-keys/801dbb99-34e6-43c0-a6b0-a45695c2a653

{
  "description" : "test-修改",
  "allow_all" : true
}

权限范围自定义

PUT https://{endpoint}/v2/{project_id}/maas/api-auth/api-keys/801dbb99-34e6-43c0-a6b0-a45695c2a653

{
  "description" : "test-修改1",
  "allow_all" : false,
  "ip_whitelist" : [ "192.168.1.1", "192.168.1.10-192.168.1.100", "192.168.10.0/24" ],
  "resident_model_version_whitelist" : {
    "overall" : "",
    "whitelist" : [ {
      "resident_model_id" : "8f7b4934-88a5-48ed-8188-f479e202453f",
      "version_whitelist" : "all"
    }, {
      "resident_model_id" : "2e34e492-5920-4d12-9910-7cef0d0f6a44",
      "version_whitelist" : "91d41083-2b04-4f78-b346-ba455ee4fa62"
    } ]
  },
  "endpoint_whitelist" : {
    "overall" : "none",
    "whitelist" : [ ]
  }
}

响应示例

状态码：200

{
  "id" : "801dbb99-34e6-43c0-a6b0-a45695c2a653",
  "label" : "ak-ooKnYK",
  "description" : "test-修改1",
  "allow_all" : false,
  "ip_whitelist" : [ "192.168.1.1", "192.168.1.10-192.168.1.100", "192.168.10.0/24" ],
  "resident_model_version_whitelist" : {
    "overall" : "",
    "whitelist" : [ {
      "resident_model_id" : "8f7b4934-88a5-48ed-8188-f479e202453f",
      "version_whitelist" : "all"
    }, {
      "resident_model_id" : "2e34e492-5920-4d12-9910-7cef0d0f6a44",
      "version_whitelist" : "91d41083-2b04-4f78-b346-ba455ee4fa62"
    } ]
  },
  "endpoint_whitelist" : {
    "overall" : "none",
    "whitelist" : [ ]
  }
}

状态码：403

{
  "error_msg" : "Invalid token.",
  "error_code" : "ModelArts.0104"
}

状态码

状态码	描述
200	修改API Key成功
403	用户鉴权token异常

错误码

请参见错误码。

父主题： API Key鉴权管理

上一篇：创建API Key

下一篇：删除API Key