如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

凭据库

存储 MCP 连接或沙盒发出的请求所需的机密值。

凭据库将凭据与智能体的指令和配置分开存储。通过 vault_ids 将凭据库关联到会话后,会话就可以使用其中的凭据。

根据请求的发起位置选择凭据类型:

请求 凭据类型 会话如何使用凭据
OpenAI 发起的 MCP 连接 static_bearer 或 mcp_oauth OpenAI 使用凭据向配置的 MCP 服务器验证身份。
OpenAI 托管的沙盒发出的 API 请求 environment_variable 代码使用含有占位符的环境变量。对于发往获准主机的请求,网络代理会将占位符替换为机密值。

例如,沙盒可以使用凭据库中的机密值调用 GitHub REST API。具体步骤请参阅在沙盒发出的 API 请求中使用凭据库中的机密值。

检索凭据库或凭据时,API 不会返回其中的机密值。有关其他 MCP 连接的身份验证方式,请参阅 MCP 身份验证选项。

权限

如果您使用受限的应用密钥,请为其授予以下权限:

  • api.vaults.read,用于列出和检索凭据库及凭据。
  • api.vaults.write,用于创建、更新或删除凭据库及凭据。

创建并使用凭据库存储 MCP 机密值

您需要准备 API 客户端、MCP 服务器的 URL(mcp_url)以及该服务器的访问令牌(access_token)。以下示例使用 GitHub 工具。

首先,创建凭据库:

创建凭据库
const vault = await client.beta.agents.vaults.create({
  name: "GitHub credentials",
  metadata: {
    external_user_id: "user_123",
  },
});

将凭据库的 ID 保存为 vault_id,然后添加令牌。mcp_server_url 将凭据绑定到指定的服务器:

存储持有者令牌
// Replace the illustrative IDs and URLs below with your own resource values.
const vaultId = "vault_123";
const mcpUrl = "https://api.githubcopilot.com/mcp/";
const accessToken = process.env.GITHUB_TOKEN;

if (!accessToken) {
  throw new Error("Set GITHUB_TOKEN");
}

const credential = await client.beta.agents.vaults.credentials.create(vaultId, {
  name: "GitHub access token",
  auth: {
    type: "static_bearer",
    mcp_server_url: mcpUrl,
    token: accessToken,
  },
});

将凭据 ID 保存为 credential_id,以便后续更新凭据。

创建会话时,通过 vault_ids 传入之前保存的凭据库 ID。在 MCP 配置中使用相同的服务器 URL:

将凭据库关联到会话
// Replace the illustrative IDs and URLs below with your own resource values.
const mcpUrl = "https://api.githubcopilot.com/mcp/";
const vaultId = "vault_123";

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "github",
        transport: {
          type: "http",
          server_url: mcpUrl,
        },
        allowed_tools: ["search_issues", "issue_read"],
        required: true,
        connection_origin: "service",
      },
    ],
  },
  environment: {
    type: "none",
  },
  input: "Find open bugs reported in the last week.",
  vault_ids: [vaultId],
});

Agents API 会选择与服务器 URL 匹配的凭据。如果关联的凭据中有多个匹配项,请设置 MCP 工具的 credential_id 来指定要使用的凭据。

在沙盒发出的 API 请求中使用凭据库中的机密值

使用 environment_variable 类型的凭据,为 OpenAI 托管的沙盒发出的 API 请求提供机密值。沙盒通过指定的环境变量获取占位符,实际的机密值始终保存在沙盒外。

此流程要求使用 openai_hosted 环境。它不会向自托管环境或由应用运行的函数工具提供凭据。

存储 API 令牌

按上文所述创建凭据库。然后向 POST /v1/vaults/{vault_id}/credentials 发送创建凭据的请求,并在请求中包含以下字段:

字段 GitHub API 令牌对应的值
name GitHub API token
auth.type environment_variable
auth.secret_name GITHUB_TOKEN
auth.secret_value 从应用中用于保存机密值的环境变量读取的令牌。
auth.networking.type limited
auth.networking.allowed_hosts ["api.github.com"]

secret_name 指定沙盒代码读取的环境变量名。secret_value 是实际的凭据值。请勿将其写入提示、源文件或日志。

在 allowed_hosts 中填写确切的主机名,不要包含协议前缀、路径、端口或通配符。代理仅向使用 443 或 8443 端口的 HTTPS 目标提供机密值。

将凭据库关联到托管会话

除 agent 外,您还需要在创建会话时提供以下字段。请将 vault_123 替换为 API 返回的凭据库 ID:

{
  "vault_ids": ["vault_123"],
  "environment": {
    "type": "openai_hosted",
    "network": {
      "access": "restricted",
      "allowed_domains": ["api.github.com"]
    }
  }
}

两个主机列表各有用途。allowed_domains 指定沙盒可以连接哪些主机。凭据的 allowed_hosts 指定代理可以向哪些主机提供该凭据的机密值。

网络访问受限时,请在 allowed_domains 中列出各凭据指定的所有主机。对于使用环境变量凭据的会话,请勿将 network.access 设为 disabled。

关联到同一会话的每个环境变量凭据都必须使用唯一的 secret_name。请勿在 environment.env 中重复定义该名称。

从沙盒调用 API

向智能体发送消息,让它在沙盒中运行以下命令:

curl https://api.github.com/user \
  -H "Authorization: Bearer $GITHUB_TOKEN"

该命令从 GITHUB_TOKEN 读取占位符。代理在向 api.github.com 发送请求之前,将占位符替换为实际令牌。请求成功后,API 会以 JSON 格式返回通过身份验证的 GitHub 用户的账户详情。在沙盒中打印该变量只会显示占位符,不会显示令牌。

请在 HTTPS 请求头中原样传递占位符。沙盒代码无法通过占位符获取实际的机密值来执行本地计算,例如为请求签名。对于此类任务,请将凭据保存在您的应用中,并通过函数工具提供相应操作。

使用 OAuth 凭据

您的应用负责处理提供方的授权和用户同意流程。使用 auth.type: "mcp_oauth" 存储获得的授权信息。如果已知访问令牌的过期时间,请将 expires_at 设为 RFC 3339 格式的过期时间戳。

以下示例使用从提供方的 OAuth 流程中获得的值。包含 refresh 字段即可让 Agents API 刷新令牌:

存储 OAuth 授权信息
// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
const vaultId = "vault_123";
const mcpUrl = "https://mcp.example.com/mcp";
const accessToken = process.env.OAUTH_ACCESS_TOKEN;
const expiresAt = "2030-01-01T00:00:00Z";
const tokenEndpoint = "https://auth.example.com/oauth/token";
const clientId = "example-client-id";
const refreshToken = process.env.OAUTH_REFRESH_TOKEN;

if (!accessToken || !refreshToken) {
  throw new Error("Set OAUTH_ACCESS_TOKEN and OAUTH_REFRESH_TOKEN");
}

const credential = await client.beta.agents.vaults.credentials.create(vaultId, {
  name: "Example MCP OAuth credential",
  auth: {
    type: "mcp_oauth",
    mcp_server_url: mcpUrl,
    access_token: accessToken,
    expires_at: expiresAt,
    refresh: {
      token_endpoint: tokenEndpoint,
      client_id: clientId,
      refresh_token: refreshToken,
      token_endpoint_auth: {
        type: "none",
      },
    },
  },
});

请使用提供方要求的令牌端点身份验证方式。示例使用 none,此外还支持 client_secret_basic 和 client_secret_post。有关字段说明,请参阅创建凭据的 API 参考。

如果过期令牌无法刷新,请提供有效的新令牌。令牌过期不会导致凭据或其所属的凭据库被删除。

轮换或移除凭据

更新凭据可替换其机密值,同时保留原有的 ID 和身份验证类型。对于 MCP 凭据,服务器 URL 也保持不变。更新 OAuth 凭据时,请使用之前保存的 vault_id 和 credential_id,并提供新令牌及其过期时间:

轮换 OAuth 令牌
// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
const credentialId = "cred_123";
const vaultId = "vault_123";
const accessToken = process.env.OAUTH_ACCESS_TOKEN;
const expiresAt = "2030-01-01T00:00:00Z";

const credential = await client.beta.agents.vaults.credentials.update(
  credentialId,
  {
    vault_id: vaultId,
    ...{
      auth: {
        type: "mcp_oauth",
        access_token: accessToken,
        expires_at: expiresAt,
      },
    },
  }
);

如果新令牌有过期时间,请提供 expires_at。提供新访问令牌时,如果省略过期时间,系统会清除已保存的过期时间。显式传入 null 也会清除该值。

对于环境变量凭据,请将 auth.type: "environment_variable" 和新的 auth.secret_value 发送到 POST /v1/vaults/{vault_id}/credentials/{credential_id}。请创建新会话以使用更新后的凭据。更新凭据库不会更改现有沙盒中已配置的凭据。

如需更改 secret_name 或 networking,请创建新凭据。

不再需要某个凭据时,请删除该凭据。删除凭据库会移除该库及其中的所有凭据。

删除已存储的凭据不会撤销提供方签发的原始令牌,也不会停止正在运行的会话。您的应用负责在提供方一侧撤销令牌以及取消会话。