更新 Credential

描述

原地更新指定 Vault 下处于 active 状态的 Credential。请求采用 merge 风格的补丁，未传字段保持原值，适合在不重建 Credential 的情况下轮换密钥。Forward 会校验调用方对所属 Vault 的写权限；敏感认证字段只写入，不会在响应中回显。

路径

POST /api/v1/forward/vaults/{id}/credentials/{cred_id}

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT 或 SAT>`
`Content-Type`	是	`application/json`

路径参数

参数	类型	必选	说明
`id`	string	是	Vault ID。
`cred_id`	string	是	Credential ID。

查询参数

参数	类型	必选	说明
`identity_id`	string	否	仅在操作 Identity 归属资源时使用，非必填；PAT 场景可显式传入，未传时为管理员视角；SAT 场景请签发 Identity 维度凭证且不要显式携带该参数，否则返回 HTTP 400（详见 Identity 归属）。

请求体

请求采用部分更新语义，仅接受 auth 与 metadata，至少提供一个字段。

字段	类型	必选	说明
`auth`	object	否	按当前 Credential 类型部分更新认证信息。提供时必须包含 `type`，且必须与当前类型一致。
`metadata`	object \| null	否	对现有 metadata 做 merge patch。对象中的 `null` 删除对应键；顶层 `null` 清空全部 metadata。`created_by` 是保留键，不可更新。

Credential 类型、MCP Server URL、环境变量 secret_name 以及 OAuth refresh 配置中的 client_id、token_endpoint 均不可通过该接口修改。

`static_bearer`

字段	类型	必选	说明
`type`	string	是	固定为 `static_bearer`。
`token`	string	否	替换 Bearer token，仅写入，响应不回显。

`mcp_oauth`

字段	类型	必选	说明
`type`	string	是	固定为 `mcp_oauth`。
`access_token`	string	否	替换 access token。
`expires_at`	string \| null	否	RFC 3339 时间；`null` 清除过期时间。
`refresh`	object	否	部分更新既有 refresh 配置。不能给原本没有 refresh 配置的 Credential 新增该配置。

refresh 对象支持：

字段	类型	必选	说明
`refresh_token`	string	否	替换 refresh token。
`scope`	string \| null	否	替换或清除 scope。
`token_endpoint_auth`	object	否	更新 token endpoint 的认证配置。

`environment_variable`

字段	类型	必选	说明
`type`	string	是	固定为 `environment_variable`。
`secret_value`	string	否	替换密文值，仅写入，响应不回显。

示例请求

curl -X POST "https://api.qoder.com.cn/api/v1/forward/vaults/vault_xxx/credentials/vcred_xxx" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "static_bearer",
      "token": "new-secret-token"
    },
    "metadata": {
      "rotated_by": "console"
    }
  }'

示例响应

HTTP 200 OK

{
  "id": "vcred_xxx",
  "type": "vault_credential",
  "vault_id": "vault_xxx",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://mcp.example.com"
  },
  "display_name": "",
  "metadata": {
    "rotated_by": "console"
  },
  "archived_at": null,
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-08-27T12:00:00Z"
}

响应为 Vault credential 对象，所有 token、secret 等密文字段均不回显。

Credential 更新具有 write-only 属性。若客户端没有收到成功响应，后续 GET 只能读取脱敏状态，不能证明本次密钥是否已生效，因此不要自动重试密钥更新。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	请求体或路径参数非法，包括没有可更新字段、包含不支持字段、`auth.type` 缺失或与当前类型不一致、字段值非法，或对没有 refresh 配置的 Credential 修改 `refresh`。
400	`invalid_request_error`	传入保留键 `created_by` 时，`message` 为 `metadata key "created_by" is reserved`。
401	`authentication_error`	缺少或无效的认证令牌。
403	`permission_error`	当前调用方无权访问所属 Vault 或 Credential。
404	`not_found_error`	Vault/Credential 不存在或不可见。
409	`conflict_error`	Vault 或 Credential 已归档，或资源状态冲突。
500/502/503	`api_error`	Forward 或依赖服务失败。

Credential 请求中的认证信息属于敏感数据。部分详细校验消息会被替换为统一的脱敏文案，HTTP 状态码和错误 type 保持不变。

​描述

​路径

​请求头

​路径参数

​查询参数

​请求体

​static_bearer

​mcp_oauth

​environment_variable

​示例请求

​示例响应

​错误码

描述

路径

请求头