1# Vaults
2
3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4
5A 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.
6
7Vaults 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).
8
9## Permissions
10
11For a restricted application key, grant:
12
13- `api.vaults.read` to list and retrieve vaults and credentials.
14- `api.vaults.write` to create, update, or delete them.
15
16
17
18
19## Create and use a vault
20
21Use your API client, the MCP server URL (`mcp_url`), and an access token for that server (`access_token`). The examples use GitHub tools.
22
23First, create a vault:
24
25Create a vault
26
27```javascript
28const vault = await client.beta.agents.vaults.create({
29 name: "GitHub credentials",
30 metadata: {
31 external_user_id: "user_123",
32 },
33});
34```
35
36```python
37vault = client.beta.agents.vaults.create(
38 name="GitHub credentials", metadata={"external_user_id": "user_123"}
39)
40```
41
42```go
43vault, 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```
52
53```java
54var vault =
55 client
56 .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```
68
69```ruby
70vault = client.beta.agents.vaults.create(
71 name: "GitHub credentials",
72 metadata: { external_user_id: "user_123" }
73)
74```
75
76
77Save its ID as `vault_id`, then add the token. `mcp_server_url` binds the credential to that server:
78
79Store a bearer token
80
81```javascript
82// 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;
86
87const 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```
96
97```python
98# 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"]
102
103credential = 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```
113
114```go
115// 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")
119
120credential, 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```
135
136```java
137// 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");
141
142var credential =
143 client
144 .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```
159
160```ruby
161# 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")
165
166credential = 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_token
173 }
174)
175```
176
177
178Save the credential ID as `credential_id` for later updates.
179
180
181
182
183Pass the saved ID in `vault_ids` when creating a session. Use the same server URL in the MCP configuration:
184
185Attach the vault to a session
186
187```javascript
188// Replace the illustrative IDs and URLs below with your own resource values.
189const mcpUrl = "https://api.githubcopilot.com/mcp/";
190const vaultId = "vault_123";
191
192const 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```
216
217```python
218# Replace the illustrative IDs and URLs below with your own resource values.
219mcp_url = "https://api.githubcopilot.com/mcp/"
220vault_id = "vault_123"
221
222session = 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```
244
245```go
246// Replace the illustrative IDs and URLs below with your own resource values.
247mcpUrl := "https://api.githubcopilot.com/mcp/"
248vaultId := "vault_123"
249
250session, 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```
274
275```java
276// Replace the illustrative IDs and URLs below with your own resource values.
277String mcpUrl = "https://api.githubcopilot.com/mcp/";
278String vaultId = "vault_123";
279
280var session =
281 client
282 .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```
306
307```ruby
308# Replace the illustrative IDs and URLs below with your own resource values.
309mcp_url = "https://api.githubcopilot.com/mcp/"
310vault_id = "vault_123"
311
312session = 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_url
322 },
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```
337
338
339The 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.
340
341
342
343
344## Use OAuth credentials
345
346Your 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.
347
348The following example uses values from your provider's OAuth flow. Include `refresh` to let the Agents API refresh the token:
349
350Store an OAuth grant
351
352```javascript
353// 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;
362
363const 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```
381
382```python
383# 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"]
392
393credential = 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```
410
411```go
412// 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")
421
422credential, 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```
444
445```java
446// 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");
455
456var credential =
457 client
458 .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```
481
482```ruby
483# 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")
492
493credential = 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```
510
511
512Use 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.
513
514If an expired token cannot be refreshed, supply a valid replacement. Token expiry does not delete the credential or its vault.
515
516
517
518
519
520
521
522
523
524
525
526
527## Rotate or remove credentials
528
529[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:
530
531Rotate an OAuth token
532
533```javascript
534// 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";
540
541const 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```
555
556```python
557# 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"
563
564credential = 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```
574
575```go
576// 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"
582
583credential, 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```
598
599```java
600// 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";
606
607var credential =
608 client
609 .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```
624
625```ruby
626# 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"
632
633credential = 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_at
640 }
641)
642```
643
644
645Include `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.
646
647[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.
648
649Deleting 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).
