Repository Public
1# Vaults23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45A vault stores credentials for MCP connections from OpenAI. Attach it to a session so the agent can use authenticated tools without receiving the secret values.67Vaults support bearer tokens and existing OAuth grants. For connections from your environment, use the other [MCP authentication options](https://developers.openai.com/api/docs/guides/agents-api/tools/mcp#add-authentication).89## Permissions1011For a restricted application key, grant:1213- `api.vaults.read` to list and retrieve vaults and credentials.14- `api.vaults.write` to create, update, or delete them.1516171819## Create and use a vault2021Use your API client, the MCP server URL (`mcp_url`), and an access token for that server (`access_token`). The examples use GitHub tools.2223First, create a vault:2425Create a vault2627```javascript28const vault = await client.beta.agents.vaults.create({29 name: "GitHub credentials",30 metadata: {31 external_user_id: "user_123",32 },33});34```3536```python37vault = client.beta.agents.vaults.create(38 name="GitHub credentials", metadata={"external_user_id": "user_123"}39)40```4142```go43vault, err := client.Beta.Agents.Vaults.New(ctx,44 openai.BetaAgentVaultNewParams{45 Name: openai.String("GitHub credentials"),46 Metadata: map[string]string{"external_user_id": "user_123"},47 })48if err != nil {49 panic(err)50}51```5253```java54var vault =55 client56 .beta()57 .agents()58 .vaults()59 .create(60 VaultCreateParams.builder()61 .name("GitHub credentials")62 .metadata(63 VaultCreateParams.Metadata.builder()64 .putAdditionalProperty("external_user_id", JsonValue.from("user_123"))65 .build())66 .build());67```6869```ruby70vault = client.beta.agents.vaults.create(71 name: "GitHub credentials",72 metadata: { external_user_id: "user_123" }73)74```757677Save its ID as `vault_id`, then add the token. `mcp_server_url` binds the credential to that server:7879Store a bearer token8081```javascript82// Replace the illustrative IDs and URLs below with your own resource values.83const vaultId = "vault_123";84const mcpUrl = "https://api.githubcopilot.com/mcp/";85const accessToken = process.env.GITHUB_TOKEN;8687const credential = await client.beta.agents.vaults.credentials.create(vaultId, {88 name: "GitHub access token",89 auth: {90 type: "static_bearer",91 mcp_server_url: mcpUrl,92 token: accessToken,93 },94});95```9697```python98# Replace the illustrative IDs and URLs below with your own resource values.99vault_id = "vault_123"100mcp_url = "https://api.githubcopilot.com/mcp/"101access_token = os.environ["GITHUB_TOKEN"]102103credential = client.beta.agents.vaults.credentials.create(104 vault_id,105 name="GitHub access token",106 auth={107 "type": "static_bearer",108 "mcp_server_url": mcp_url,109 "token": access_token,110 },111)112```113114```go115// Replace the illustrative IDs and URLs below with your own resource values.116vaultId := "vault_123"117mcpUrl := "https://api.githubcopilot.com/mcp/"118accessToken := os.Getenv("GITHUB_TOKEN")119120credential, err := client.Beta.Agents.Vaults.Credentials.New(ctx,121 vaultId,122 openai.BetaAgentVaultCredentialNewParams{123 Name: "GitHub access token",124 Auth: openai.CredentialAuthCreateParamUnion{125 OfParamStaticBearer: &openai.CredentialAuthCreateParamStaticBearer{126 McpServerURL: mcpUrl,127 Token: accessToken,128 },129 },130 })131if err != nil {132 panic(err)133}134```135136```java137// Replace the illustrative IDs and URLs below with your own resource values.138String vaultId = "vault_123";139String mcpUrl = "https://api.githubcopilot.com/mcp/";140String accessToken = System.getenv("GITHUB_TOKEN");141142var credential =143 client144 .beta()145 .agents()146 .vaults()147 .credentials()148 .create(149 CredentialCreateParams.builder()150 .vaultId(vaultId)151 .name("GitHub access token")152 .auth(153 CredentialAuthCreateParam.StaticBearer.builder()154 .mcpServerUrl(mcpUrl)155 .token(accessToken)156 .build())157 .build());158```159160```ruby161# Replace the illustrative IDs and URLs below with your own resource values.162vault_id = "vault_123"163mcp_url = "https://api.githubcopilot.com/mcp/"164access_token = ENV.fetch("GITHUB_TOKEN")165166credential = client.beta.agents.vaults.credentials.create(167 vault_id,168 name: "GitHub access token",169 auth: {170 type: "static_bearer",171 mcp_server_url: mcp_url,172 token: access_token173 }174)175```176177178Save the credential ID as `credential_id` for later updates.179180181182183Pass the saved ID in `vault_ids` when creating a session. Use the same server URL in the MCP configuration:184185Attach the vault to a session186187```javascript188// Replace the illustrative IDs and URLs below with your own resource values.189const mcpUrl = "https://api.githubcopilot.com/mcp/";190const vaultId = "vault_123";191192const session = await client.beta.agents.sessions.create({193 agent: {194 model: "gpt-6-astra",195 tools: [196 {197 type: "mcp",198 server_label: "github",199 transport: {200 type: "http",201 server_url: mcpUrl,202 },203 allowed_tools: ["search_issues", "issue_read"],204 required: true,205 connection_origin: "service",206 },207 ],208 },209 environment: {210 type: "none",211 },212 input: "Find open bugs reported in the last week.",213 vault_ids: [vaultId],214});215```216217```python218# Replace the illustrative IDs and URLs below with your own resource values.219mcp_url = "https://api.githubcopilot.com/mcp/"220vault_id = "vault_123"221222session = client.beta.agents.sessions.create(223 agent={224 "model": "gpt-6-astra",225 "tools": [226 {227 "type": "mcp",228 "server_label": "github",229 "transport": {230 "type": "http",231 "server_url": mcp_url,232 },233 "allowed_tools": ["search_issues", "issue_read"],234 "required": True,235 "connection_origin": "service",236 }237 ],238 },239 environment={"type": "none"},240 input="Find open bugs reported in the last week.",241 vault_ids=[vault_id],242)243```244245```go246// Replace the illustrative IDs and URLs below with your own resource values.247mcpUrl := "https://api.githubcopilot.com/mcp/"248vaultId := "vault_123"249250session, err := client.Beta.Agents.Sessions.New(ctx,251 openai.BetaAgentSessionNewParams{252 Agent: openai.BetaAgentSessionNewParamsAgent{253 Model: openai.String("gpt-6-astra"),254 Tools: []openai.AgentToolParamUnion{255 {256 OfParamMcp: &openai.AgentToolParamMcp{257 ServerLabel: "github",258 Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: mcpUrl}},259 AllowedTools: []string{"search_issues", "issue_read"},260 Required: openai.Bool(true),261 ConnectionOrigin: "service",262 },263 },264 },265 },266 Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},267 Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Find open bugs reported in the last week.")},268 VaultIDs: []string{vaultId},269 })270if err != nil {271 panic(err)272}273```274275```java276// Replace the illustrative IDs and URLs below with your own resource values.277String mcpUrl = "https://api.githubcopilot.com/mcp/";278String vaultId = "vault_123";279280var session =281 client282 .beta()283 .agents()284 .sessions()285 .create(286 SessionCreateParams.builder()287 .agent(288 SessionCreateParams.Agent.builder()289 .model("gpt-6-astra")290 .addTool(291 AgentToolParam.Mcp.builder()292 .serverLabel("github")293 .transport(294 McpTransportParam.Http.builder().serverUrl(mcpUrl).build())295 .allowedTools(List.of("search_issues", "issue_read"))296 .required(true)297 .connectionOrigin(298 AgentToolParam.Mcp.ConnectionOrigin.of("service"))299 .build())300 .build())301 .environmentNone()302 .input("Find open bugs reported in the last week.")303 .vaultIds(List.of(vaultId))304 .build());305```306307```ruby308# Replace the illustrative IDs and URLs below with your own resource values.309mcp_url = "https://api.githubcopilot.com/mcp/"310vault_id = "vault_123"311312session = client.beta.agents.sessions.create(313 agent: {314 model: "gpt-6-astra",315 tools: [316 {317 type: "mcp",318 server_label: "github",319 transport: {320 type: "http",321 server_url: mcp_url322 },323 allowed_tools: [324 "search_issues",325 "issue_read"326 ],327 required: true,328 connection_origin: "service"329 }330 ]331 },332 environment: { type: "none" },333 input: "Find open bugs reported in the last week.",334 vault_ids: [vault_id]335)336```337338339The Agents API selects a credential that matches the server URL. If several attached credentials match, set the MCP tool's `credential_id` to select one. Retrieving a vault or credential does not return its secret values.340341342343344## Use OAuth credentials345346Your application handles the provider's authorization and consent flow. Store the resulting grant with `auth.type: "mcp_oauth"`. Set `expires_at` to the access token's expiry as an RFC 3339 timestamp, if known.347348The following example uses values from your provider's OAuth flow. Include `refresh` to let the Agents API refresh the token:349350Store an OAuth grant351352```javascript353// Replace the illustrative expiry with your access token's actual expiry.354// Replace the illustrative IDs and URLs below with your own resource values.355const vaultId = "vault_123";356const mcpUrl = "https://mcp.example.com/mcp";357const accessToken = process.env.OAUTH_ACCESS_TOKEN;358const expiresAt = "2030-01-01T00:00:00Z";359const tokenEndpoint = "https://auth.example.com/oauth/token";360const clientId = "example-client-id";361const refreshToken = process.env.OAUTH_REFRESH_TOKEN;362363const credential = await client.beta.agents.vaults.credentials.create(vaultId, {364 name: "Example MCP OAuth credential",365 auth: {366 type: "mcp_oauth",367 mcp_server_url: mcpUrl,368 access_token: accessToken,369 expires_at: expiresAt,370 refresh: {371 token_endpoint: tokenEndpoint,372 client_id: clientId,373 refresh_token: refreshToken,374 token_endpoint_auth: {375 type: "none",376 },377 },378 },379});380```381382```python383# Replace the illustrative expiry with your access token's actual expiry.384# Replace the illustrative IDs and URLs below with your own resource values.385vault_id = "vault_123"386mcp_url = "https://mcp.example.com/mcp"387access_token = os.environ["OAUTH_ACCESS_TOKEN"]388expires_at = "2030-01-01T00:00:00Z"389token_endpoint = "https://auth.example.com/oauth/token"390client_id = "example-client-id"391refresh_token = os.environ["OAUTH_REFRESH_TOKEN"]392393credential = client.beta.agents.vaults.credentials.create(394 vault_id,395 name="Example MCP OAuth credential",396 auth={397 "type": "mcp_oauth",398 "mcp_server_url": mcp_url,399 "access_token": access_token,400 "expires_at": expires_at,401 "refresh": {402 "token_endpoint": token_endpoint,403 "client_id": client_id,404 "refresh_token": refresh_token,405 "token_endpoint_auth": {"type": "none"},406 },407 },408)409```410411```go412// Replace the illustrative expiry with your access token's actual expiry.413// Replace the illustrative IDs and URLs below with your own resource values.414vaultId := "vault_123"415mcpUrl := "https://mcp.example.com/mcp"416accessToken := os.Getenv("OAUTH_ACCESS_TOKEN")417expiresAt := "2030-01-01T00:00:00Z"418tokenEndpoint := "https://auth.example.com/oauth/token"419clientId := "example-client-id"420refreshToken := os.Getenv("OAUTH_REFRESH_TOKEN")421422credential, err := client.Beta.Agents.Vaults.Credentials.New(ctx,423 vaultId,424 openai.BetaAgentVaultCredentialNewParams{425 Name: "Example MCP OAuth credential",426 Auth: openai.CredentialAuthCreateParamUnion{427 OfParamMcpOAuth: &openai.CredentialAuthCreateParamMcpOAuth{428 McpServerURL: mcpUrl,429 AccessToken: accessToken,430 ExpiresAt: openai.String(expiresAt),431 Refresh: openai.CredentialAuthCreateParamMcpOAuthRefresh{432 TokenEndpoint: tokenEndpoint,433 ClientID: clientId,434 RefreshToken: refreshToken,435 TokenEndpointAuth: openai.McpOAuthTokenEndpointAuthCreateParamUnion{OfParamNone: &openai.McpOAuthTokenEndpointAuthCreateParamNone{}},436 },437 },438 },439 })440if err != nil {441 panic(err)442}443```444445```java446// Replace the illustrative expiry with your access token's actual expiry.447// Replace the illustrative IDs and URLs below with your own resource values.448String vaultId = "vault_123";449String mcpUrl = "https://mcp.example.com/mcp";450String accessToken = System.getenv("OAUTH_ACCESS_TOKEN");451String expiresAt = "2030-01-01T00:00:00Z";452String tokenEndpoint = "https://auth.example.com/oauth/token";453String clientId = "example-client-id";454String refreshToken = System.getenv("OAUTH_REFRESH_TOKEN");455456var credential =457 client458 .beta()459 .agents()460 .vaults()461 .credentials()462 .create(463 CredentialCreateParams.builder()464 .vaultId(vaultId)465 .name("Example MCP OAuth credential")466 .auth(467 CredentialAuthCreateParam.McpOAuth.builder()468 .mcpServerUrl(mcpUrl)469 .accessToken(accessToken)470 .expiresAt(expiresAt)471 .refresh(472 CredentialAuthCreateParam.McpOAuth.Refresh.builder()473 .tokenEndpoint(tokenEndpoint)474 .clientId(clientId)475 .refreshToken(refreshToken)476 .tokenEndpointAuthNone()477 .build())478 .build())479 .build());480```481482```ruby483# Replace the illustrative expiry with your access token's actual expiry.484# Replace the illustrative IDs and URLs below with your own resource values.485vault_id = "vault_123"486mcp_url = "https://mcp.example.com/mcp"487access_token = ENV.fetch("OAUTH_ACCESS_TOKEN")488expires_at = "2030-01-01T00:00:00Z"489token_endpoint = "https://auth.example.com/oauth/token"490client_id = "example-client-id"491refresh_token = ENV.fetch("OAUTH_REFRESH_TOKEN")492493credential = client.beta.agents.vaults.credentials.create(494 vault_id,495 name: "Example MCP OAuth credential",496 auth: {497 type: "mcp_oauth",498 mcp_server_url: mcp_url,499 access_token: access_token,500 expires_at: expires_at,501 refresh: {502 token_endpoint: token_endpoint,503 client_id: client_id,504 refresh_token: refresh_token,505 token_endpoint_auth: { type: "none" }506 }507 }508)509```510511512Use the token endpoint authentication method required by your provider. The example uses `none`; `client_secret_basic` and `client_secret_post` are also supported. See the [credential creation reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/vaults/subresources/credentials/methods/create) for the fields.513514If an expired token cannot be refreshed, supply a valid replacement. Token expiry does not delete the credential or its vault.515516517518519520521522523524525526527## Rotate or remove credentials528529[Update a credential](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/vaults/subresources/credentials/methods/update) to replace its token without changing its ID, authentication type, or server URL. For OAuth, use the saved `vault_id` and `credential_id` with the replacement token and expiry:530531Rotate an OAuth token532533```javascript534// Replace the illustrative expiry with your access token's actual expiry.535// Replace the illustrative IDs and URLs below with your own resource values.536const credentialId = "cred_123";537const vaultId = "vault_123";538const accessToken = process.env.OAUTH_ACCESS_TOKEN;539const expiresAt = "2030-01-01T00:00:00Z";540541const credential = await client.beta.agents.vaults.credentials.update(542 credentialId,543 {544 vault_id: vaultId,545 ...{546 auth: {547 type: "mcp_oauth",548 access_token: accessToken,549 expires_at: expiresAt,550 },551 },552 }553);554```555556```python557# Replace the illustrative expiry with your access token's actual expiry.558# Replace the illustrative IDs and URLs below with your own resource values.559credential_id = "cred_123"560vault_id = "vault_123"561access_token = os.environ["OAUTH_ACCESS_TOKEN"]562expires_at = "2030-01-01T00:00:00Z"563564credential = client.beta.agents.vaults.credentials.update(565 credential_id,566 vault_id=vault_id,567 auth={568 "type": "mcp_oauth",569 "access_token": access_token,570 "expires_at": expires_at,571 },572)573```574575```go576// Replace the illustrative expiry with your access token's actual expiry.577// Replace the illustrative IDs and URLs below with your own resource values.578vaultId := "vault_123"579credentialId := "cred_123"580accessToken := os.Getenv("OAUTH_ACCESS_TOKEN")581expiresAt := "2030-01-01T00:00:00Z"582583credential, err := client.Beta.Agents.Vaults.Credentials.Update(ctx,584 vaultId,585 credentialId,586 openai.BetaAgentVaultCredentialUpdateParams{587 Auth: openai.CredentialAuthRotateParamUnion{588 OfParamMcpOAuth: &openai.CredentialAuthRotateParamMcpOAuth{589 AccessToken: openai.String(accessToken),590 ExpiresAt: openai.String(expiresAt),591 },592 },593 })594if err != nil {595 panic(err)596}597```598599```java600// Replace the illustrative expiry with your access token's actual expiry.601// Replace the illustrative IDs and URLs below with your own resource values.602String credentialId = "cred_123";603String vaultId = "vault_123";604String accessToken = System.getenv("OAUTH_ACCESS_TOKEN");605String expiresAt = "2030-01-01T00:00:00Z";606607var credential =608 client609 .beta()610 .agents()611 .vaults()612 .credentials()613 .update(614 CredentialUpdateParams.builder()615 .credentialId(credentialId)616 .vaultId(vaultId)617 .auth(618 CredentialAuthRotateParam.McpOAuth.builder()619 .accessToken(accessToken)620 .expiresAt(expiresAt)621 .build())622 .build());623```624625```ruby626# Replace the illustrative expiry with your access token's actual expiry.627# Replace the illustrative IDs and URLs below with your own resource values.628credential_id = "cred_123"629vault_id = "vault_123"630access_token = ENV.fetch("OAUTH_ACCESS_TOKEN")631expires_at = "2030-01-01T00:00:00Z"632633credential = client.beta.agents.vaults.credentials.update(634 credential_id,635 vault_id: vault_id,636 auth: {637 type: "mcp_oauth",638 access_token: access_token,639 expires_at: expires_at640 }641)642```643644645Include `expires_at` when the replacement token expires. Supplying a new access token without an expiry clears the stored expiry; an explicit `null` also clears it.646647[Delete a credential](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/vaults/subresources/credentials/methods/delete) when you no longer need it. [Delete a vault](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/vaults/methods/delete) to remove the vault and all its credentials.648649Deleting stored credentials does not revoke the original tokens with their providers or stop a running session. Your application handles provider-side revocation and [session cancellation](https://developers.openai.com/api/docs/guides/agents-api/sessions#cancel-an-active-turn).