Vaults

A Vault holds organization-scoped credentials for service-origin HTTP MCP connections. Your application authorizes the external account, stores its credential, and chooses which Vaults a Session may use.

Create a credential

With mcpUrl and a provider-issued accessToken supplied by your application:

const vault = await client.beta.agents.vaults.create({ name: 'User authorization' });
await client.beta.agents.vaults.credentials.create(vault.id, {
  name: 'Company MCP',
  auth: {
    type: 'static_bearer',
    mcp_server_url: mcpUrl,
    token: accessToken,
  },
});

const session = await client.beta.agents.sessions.create({
  agent_id: agent.id,
  vault_ids: [vault.id],
  environment: { type: 'openai_hosted' },
});

This assumes the saved Agent has a matching service-origin HTTP MCP tool. Credential selection matches the MCP server URL. If several credentials match, select an explicit credential_id. The chosen identity remains attached to the Session; deletion does not silently switch it to a different identity.

OAuth credentials

mcp_oauth credentials support access-token refresh when refresh configuration is provided. Your application owns the initial OAuth login and consent flow.

Refresh supports none, client_secret_basic, and client_secret_post client authentication, scope/resource parameters, and rotated refresh tokens. Refresh and manual rotation serialize on the stored credential.

Scope and secret handling

Vault operations require api.vaults.read or api.vaults.write. Credential secrets are write-only and encrypted; returned resources omit them. Vault credentials stay in the service and are not placed in a Sandbox.

Although the SDK namespace is client.beta.agents.vaults, its HTTP path is /v1/vaults, not /v1/agents/vaults. Raw requests still require OpenAI-Beta: agents=v1.

Rotate and delete

Create, list, retrieve, rotate, and delete credentials through the Vault credentials collection. Rotation uses POST and retains the credential ID, auth type, and MCP server URL. Listings support active/archived filters and cursor pagination.

Deleting a Vault archives its credentials and clears stored secrets. It does not revoke provider-issued tokens or cancel running Sessions. Your application must revoke external tokens with their provider when that is required.