OpenAI 更新凭证库凭证

2026-11-18 18:02 更新

post /vaults/{vault_id}/credentials/{credential_id}

更新凭证元数据或轮换其只写密钥。参见凭证库指南。

路径参数

  • vault_id: string

凭证库 ID。

minLength: 0, maxLength: 1048576

  • credential_id: string

凭证库凭证的 ID。

minLength: 0, maxLength: 1048576

请求体参数

内容类型为 application/json。

  • auth: optional CredentialAuthRotateParam

此凭证现有身份验证方式使用的替换值。

  • McpOauth object { type, access_token, expires_at, refresh }

轮换用于 HTTPS MCP 目标的 OAuth 凭证。

  • type: "mcp_oauth" (default: "mcp_oauth")

对象类型,固定为 mcp_oauth。

  • "mcp_oauth"

  • access_token: optional string or null

用于替换现有值的只写 OAuth 访问令牌。

minLength: 0, maxLength: 1048576

  • expires_at: optional string or null

新的过期时间,格式为 RFC 3339 时间戳。传入 null 时清除。省略时保留原过期时间,除非同时提供新访问令牌,此时清除原过期时间。

minLength: 0, maxLength: 1048576

  • refresh: optional object { refresh_token, scope, token_endpoint_auth } or null

可选的只写更新,用于刷新令牌和客户端密钥。

  • refresh_token: optional string or null

新的刷新令牌。省略或传入 null 时沿用已存储的令牌。资源响应始终省略该值。

minLength: 0, maxLength: 1048576

  • scope: optional string or null

刷新请求使用的新版 OAuth 权限范围,以空格分隔。省略时保留原范围,传入 null 时停止发送 scope 参数。

minLength: 0, maxLength: 1048576

  • token_endpoint_auth: optional McpOauthTokenEndpointAuthRotateParam or null

为现有令牌端点身份验证方式更新客户端密钥。

  • ClientSecretBasic object { type, client_secret }

更新使用 HTTP Basic 身份验证发送的凭证。

  • type: "client_secret_basic" (default: "client_secret_basic")

对象类型,固定为 client_secret_basic。

  • "client_secret_basic"

  • client_secret: optional string or null

新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。

minLength: 0, maxLength: 1048576

  • ClientSecretPost object { type, client_secret }

更新在令牌请求体中发送的凭证。

  • type: "client_secret_post" (default: "client_secret_post")

对象类型,固定为 client_secret_post。

  • "client_secret_post"

  • client_secret: optional string or null

新的 OAuth 客户端密钥。省略或传入 null 时沿用已存储的密钥。资源响应始终省略该值。

minLength: 0, maxLength: 1048576

  • StaticBearer object { token, type }

替换此凭证为 MCP 服务器使用的 Bearer 令牌。

  • token: string

新的 Bearer 令牌。凭证资源的响应始终省略该值。

minLength: 0, maxLength: 1048576

  • type: "static_bearer" (default: "static_bearer")

对象类型,固定为 static_bearer。

  • "static_bearer"

  • EnvironmentVariable object { secret_value, type }

替换 OpenAI 托管环境凭证的密钥。环境变量名和网络配置保持原值。

  • secret_value: string

用于替换现有值的只写密钥。凭证资源始终省略该值,沙箱代码也无法直接取得。该值不得为空,不得包含回车符、换行符或 NUL 字节。

minLength: 1, maxLength: 1048576

  • type: "environment_variable" (default: "environment_variable")

对象类型,固定为 environment_variable。

  • "environment_variable"

  • metadata: optional map[string]

替换全部元数据。省略时保留原值,传入 {} 时清除。最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。

返回值

  • Credential object { id, auth, created_at, 5 more }

已存储凭证的元数据。响应始终省略机密值。

  • id: string

凭证 ID。

minLength: 0

  • auth: CredentialAuth

凭证的身份验证方式和非机密配置。

  • McpOauth object { expires_at, mcp_server_url, refresh, type }

OAuth 凭证的非机密元数据。响应始终省略令牌和客户端密钥。

  • expires_at: string or null

OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。

minLength: 0

  • mcp_server_url: string

此凭证授权访问的 HTTPS MCP 服务器 URL。

minLength: 0

  • refresh: object { client_id, resource, scope, 2 more } or null

可返回的非机密刷新元数据,省略刷新令牌和 OAuth 客户端密钥。

  • client_id: string

获取新访问令牌时使用的 OAuth 客户端 ID。

minLength: 0

  • resource: string or null

刷新时发送给 OAuth 令牌端点的资源 URI(如已配置)。

minLength: 0

  • scope: string or null

刷新时请求的 OAuth 权限范围,以空格分隔(如已配置)。

minLength: 0

  • token_endpoint: string

用于刷新的 HTTPS OAuth 令牌端点。

minLength: 0

  • token_endpoint_auth: McpOauthTokenEndpointAuth

OAuth 客户端向令牌端点进行身份验证的方式。响应省略客户端密钥。

  • None object { type }

发送客户端 ID,省略客户端密钥。

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • ClientSecretBasic object { type }

使用 HTTP Basic 身份验证发送客户端 ID 和密钥。

  • type: "client_secret_basic" (default: "client_secret_basic")

对象类型,固定为 client_secret_basic。

  • "client_secret_basic"

  • ClientSecretPost object { type }

在令牌请求体中发送客户端 ID 和密钥。

  • type: "client_secret_post" (default: "client_secret_post")

对象类型,固定为 client_secret_post。

  • "client_secret_post"

  • type: "mcp_oauth" (default: "mcp_oauth")

对象类型,固定为 mcp_oauth。

  • "mcp_oauth"

  • StaticBearer object { mcp_server_url, type }

Bearer 令牌凭证的元数据。此类凭证不支持 OAuth 自动刷新。

  • mcp_server_url: string

此凭证授权访问的 HTTPS MCP 服务器 URL。

minLength: 0

  • type: "static_bearer" (default: "static_bearer")

对象类型,固定为 static_bearer。

  • "static_bearer"

  • EnvironmentVariable object { networking, secret_name, type }

仅用于 OpenAI 托管环境的 HTTP 凭证元数据。沙箱代码收到的是占位符。代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法使用真实密钥进行本地计算,此资源的响应也始终省略真实密钥。

  • networking: CredentialNetworking

代理可将占位符替换为密钥的目标,受环境网络策略约束。

  • Unrestricted object { type }

允许为环境网络策略许可的目标替换占位符。要求 environment.network.access 为 restricted,并明确设置 allowed_domains。

  • type: "unrestricted" (default: "unrestricted")

对象类型,固定为 unrestricted。

  • "unrestricted"

  • Limited object { allowed_hosts, type }

仅允许为列出的主机替换占位符。环境网络策略也必须允许访问这些主机。

  • allowed_hosts: array of string

允许访问的 1 至 16 个不重复主机名或 IPv4 地址,统一转换为小写。条目不得包含协议、路径、端口或通配符。当前不支持 IPv6 地址。

minItems: 1, maxItems: 16

  • type: "limited" (default: "limited")

对象类型,固定为 limited。

  • "limited"

  • secret_name: string

沙箱内用于接收占位符的环境变量名。

minLength: 0

  • type: "environment_variable" (default: "environment_variable")

对象类型,固定为 environment_variable。

  • "environment_variable"

  • created_at: integer

凭证创建时的 Unix 时间戳,单位为秒。

format: int64

  • metadata: map[string]

应用定义的键值对,与此凭证关联。

  • name: string

凭证的可读名称。

minLength: 0

  • object: "vault.credential" (default: "vault.credential")

对象类型,固定为 vault.credential。

  • "vault.credential"

  • updated_at: integer

凭证上次更新时的 Unix 时间戳,单位为秒。

format: int64

  • vault_id: string

此凭证所属凭证库的 ID。

minLength: 0

示例

## 从环境变量读取 API 密钥。
## 将 VAULT_ID 设置为目标凭证库的 ID。
## 将 CREDENTIAL_ID 设置为目标凭证的 ID。
curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "metadata": {}
        }'

200 响应示例

字段名、类型值和示例标识均按接口定义保留。

{
  "id": "id",
  "auth": {
    "expires_at": "expires_at",
    "mcp_server_url": "mcp_server_url",
    "refresh": {
      "client_id": "client_id",
      "resource": "resource",
      "scope": "scope",
      "token_endpoint": "token_endpoint",
      "token_endpoint_auth": {
        "type": "none"
      }
    },
    "type": "mcp_oauth"
  },
  "created_at": 0,
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "vault.credential",
  "updated_at": 0,
  "vault_id": "vault_id"
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号