OpenAI 创建凭证库凭证
post /vaults/{vault_id}/credentials
创建凭证库凭证。机密值只写,响应始终省略。参见凭证库指南。
路径参数
vault_id: string
凭证库 ID。
minLength: 0, maxLength: 1048576
请求体参数
内容类型为 application/json。
auth: CredentialAuthCreateParam
身份验证方式和待存储的只写机密值。
McpOauth object { access_token, mcp_server_url, type, 2 more }
用于 HTTPS MCP 目标的 OAuth 凭证。
access_token: string
只写的 OAuth 访问令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0, maxLength: 1048576
type: "mcp_oauth" (default: "mcp_oauth")
对象类型,固定为 mcp_oauth。
"mcp_oauth"
expires_at: optional string or null
OAuth 访问令牌的过期时间,格式为 RFC 3339 时间戳(如已知)。
minLength: 0, maxLength: 1048576
refresh: optional object { client_id, refresh_token, token_endpoint, 3 more } or null
HTTPS OAuth 令牌端点的可选刷新配置。
client_id: string
获取新访问令牌时使用的 OAuth 客户端 ID。
minLength: 0, maxLength: 1048576
refresh_token: string
要存储的刷新令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
token_endpoint: string
用于用刷新令牌换取新访问令牌的 HTTPS OAuth 令牌端点。
minLength: 0, maxLength: 1048576
token_endpoint_auth: McpOauthTokenEndpointAuthCreateParam
OAuth 客户端向令牌端点进行身份验证的方式。
None object { type }
发送客户端 ID,省略客户端密钥。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
ClientSecretBasic object { client_secret, type }
使用 HTTP Basic 身份验证发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_basic" (default: "client_secret_basic")
对象类型,固定为 client_secret_basic。
"client_secret_basic"
ClientSecretPost object { client_secret, type }
在令牌请求体中发送客户端 ID 和密钥。
client_secret: string
要存储的 OAuth 客户端密钥。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
type: "client_secret_post" (default: "client_secret_post")
对象类型,固定为 client_secret_post。
"client_secret_post"
resource: optional string or null
刷新时要发送给 OAuth 令牌端点的资源 URI(如有必要)。
minLength: 0, maxLength: 1048576
scope: optional string or null
刷新时要请求的 OAuth 权限范围,以空格分隔(如有必要)。
minLength: 0, maxLength: 1048576
StaticBearer object { token, mcp_server_url, type }
用于 MCP 服务器的 Bearer 令牌。此类型不支持 OAuth 自动刷新。
token: string
要存储的 Bearer 令牌。凭证资源的响应始终省略该值。
minLength: 0, maxLength: 1048576
mcp_server_url: string
此凭证授权访问的 HTTPS MCP 服务器 URL。
minLength: 0, maxLength: 1048576
type: "static_bearer" (default: "static_bearer")
对象类型,固定为 static_bearer。
"static_bearer"
EnvironmentVariable object { networking, secret_name, secret_value, type }
仅用于 OpenAI 托管环境的 HTTP 凭证。沙箱收到的环境变量包含占位符。发送请求时原样使用该值。出站代理只对获准且使用 443 或 8443 端口的 HTTPS 目标将占位符替换为密钥。沙箱代码无法读取真实密钥,也无法在本地计算中使用它,例如给请求签名。
networking: CredentialNetworkingParam
代理可以替换此密钥的目标。环境网络策略也必须允许访问这些目标。
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
接收占位符的环境变量名,例如 SERVICE_API_KEY。可使用 ASCII 字母、数字和下划线,首字符必须为字母或下划线。以 CODEX_ 开头的名称以及托管代理或证书的变量名均为保留名称。
minLength: 1, maxLength: 1048576
secret_value: string
要存储的只写密钥。凭证资源始终省略该值,沙箱代码也无法直接取得。该值不得为空,不得包含回车符、换行符或 NUL 字节。
minLength: 1, maxLength: 1048576
type: "environment_variable" (default: "environment_variable")
对象类型,固定为 environment_variable。
"environment_variable"
name: string
保存前去除名称首尾空白,处理后长度必须为 1 至 256 个 UTF-8 字节。
minLength: 1, maxLength: 1048576
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。
## access_token、mcp_server_url 和 name 均为占位值。请通过机密管理流程提供真实令牌。
curl https://api.openai.com/v1/vaults/$VAULT_ID/credentials \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"auth": {
"access_token": "access_token",
"mcp_server_url": "mcp_server_url",
"type": "mcp_oauth"
},
"name": "x"
}'
201 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"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"
}
如需核对已保存的非机密元数据,可获取凭证库凭证。

TRAE-AI编程


更多建议: