For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

建议

智能体 API

智能体 SDK

ChatKit

API Dashboard
试用 ChatGPT

保管库

存储 MCP 凭证并将其关联到智能体会话。

保管库存储从 OpenAI 发起 MCP 连接所需的凭证。将保管库关联到会话后，智能体即可使用需要身份验证的工具，而无需接收凭证中的机密值。

保管库支持持有者 Token 和现有 OAuth 授权。对于从您的环境发起的连接，请使用其他 MCP 身份验证选项。

权限

对于受限的应用程序密钥，请授予以下权限：

  • api.vaults.read：用于列出和获取保管库及凭证。
  • api.vaults.write：用于创建、更新或删除保管库及凭证。

创建和使用保管库

使用您的 API 客户端、MCP 服务器 URL（mcp_url）以及该服务器的访问 Token（access_token）。以下示例使用 GitHub 工具。

首先，创建一个保管库：

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

将其 ID 保存为 vault_id，然后添加 Token。mcp_server_url 将凭证绑定到该服务器：

存储持有者 Token
// 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;

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 来选择其中一个。获取保管库或凭证时，不会返回其中的机密值。

使用 OAuth 凭证

您的应用程序负责处理提供方的授权和用户同意流程。使用 auth.type: "mcp_oauth" 存储获得的授权。如果已知访问 Token 的过期时间，请将其转换为 RFC 3339 时间戳并赋给 expires_at。

以下示例使用从提供方 OAuth 流程中获得的值。添加 refresh，以便 Agents API 刷新 Token：

存储 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;

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",
      },
    },
  },
});

请使用提供方要求的 Token 端点身份验证方法。此示例使用 none；也支持 client_secret_basic 和 client_secret_post。有关字段的说明，请参阅凭证创建参考资料。

如果已过期的 Token 无法刷新，请提供有效的替代 Token。Token 过期不会导致凭证或其所属保管库被删除。

轮换或移除凭证

通过更新凭证，您可以替换其 Token，同时保持凭证 ID、身份验证类型和服务器 URL 不变。对于 OAuth，请使用已保存的 vault_id 和 credential_id，并提供替代 Token 及其过期时间：

轮换 OAuth Token
// 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,
      },
    },
  }
);

如果替代 Token 有过期时间，请提供 expires_at。提供新的访问 Token 时，如果未指定过期时间，将清除已存储的过期时间；显式指定 null 也会将其清除。

不再需要某个凭证时，请删除该凭证。删除保管库会移除该保管库及其中的所有凭证。

删除已存储的凭证不会在提供方处撤销原始 Token，也不会停止正在运行的会话。您的应用程序负责处理提供方侧的撤销操作和会话取消。