볼트

볼트 (Vaults)

볼트(vault)는 자격 증명을 에이전트의 지시사항과 구성 밖에 저장해요. vault_ids로 세션에 연결하면 그 세션이 그 자격 증명을 사용할 수 있어요.

출처: 문서

본문

요청이 실행되는 위치에 따라 자격 증명 유형을 선택하세요:

요청	자격 증명 유형	세션이 자격 증명을 사용하는 방식
OpenAI에서의 MCP 연결	static_bearer 또는 mcp_oauth	OpenAI가 구성된 MCP 서버에 인증해요.
OpenAI 호스팅 샌드박스에서의 API 요청	environment_variable	코드가 자리 표시자를 포함한 환경 변수를 사용해요. 네트워크 프록시가 승인된 호스트에 대해 자리 표시자를 시크릿으로 바꿔요.

예를 들어 샌드박스는 볼트 시크릿으로 GitHub REST API를 호출할 수 있어요. 샌드박스에서 API 요청에 볼트 시크릿 사용을 따라가세요.

볼트나 자격 증명을 검색해도 그 시크릿 값은 반환되지 않아요. 다른 MCP 연결은 MCP 인증 옵션을 참고하세요.

권한 (Permissions)

제한된 애플리케이션 키에는 다음을 부여하세요:

• 볼트와 자격 증명을 나열·검색하려면 api.vaults.read.
• 만들고, 갱신하고, 삭제하려면 api.vaults.write.

MCP 시크릿용 볼트 만들고 사용하기 (Create and use a vault for MCP secrets)

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

vault = client.beta.agents.vaults.create(
    name="GitHub credentials", metadata={"external_user_id": "user_123"}
)

vault, err := client.Beta.Agents.Vaults.New(ctx,
	openai.BetaAgentVaultNewParams{
		Name:     openai.String("GitHub credentials"),
		Metadata: map[string]string{"external_user_id": "user_123"},
	})
if err != nil {
	panic(err)
}

var vault =
    client
        .beta()
        .agents()
        .vaults()
        .create(
            VaultCreateParams.builder()
                .name("GitHub credentials")
                .metadata(
                    VaultCreateParams.Metadata.builder()
                        .putAdditionalProperty("external_user_id", JsonValue.from("user_123"))
                        .build())
                .build());

vault = 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;

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

# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://api.githubcopilot.com/mcp/"
access_token = os.environ["GITHUB_TOKEN"]

credential = client.beta.agents.vaults.credentials.create(
    vault_id,
    name="GitHub access token",
    auth={
        "type": "static_bearer",
        "mcp_server_url": mcp_url,
        "token": access_token,
    },
)

// Replace the illustrative IDs and URLs below with your own resource values.
vaultId := "vault_123"
mcpUrl := "https://api.githubcopilot.com/mcp/"
accessToken := os.Getenv("GITHUB_TOKEN")

credential, err := client.Beta.Agents.Vaults.Credentials.New(ctx,
	vaultId,
	openai.BetaAgentVaultCredentialNewParams{
		Name: "GitHub access token",
		Auth: openai.CredentialAuthCreateParamUnion{
			OfParamStaticBearer: &openai.CredentialAuthCreateParamStaticBearer{
				McpServerURL: mcpUrl,
				Token:        accessToken,
			},
		},
	})
if err != nil {
	panic(err)
}

// Replace the illustrative IDs and URLs below with your own resource values.
String vaultId = "vault_123";
String mcpUrl = "https://api.githubcopilot.com/mcp/";
String accessToken = System.getenv("GITHUB_TOKEN");

var credential =
    client
        .beta()
        .agents()
        .vaults()
        .credentials()
        .create(
            CredentialCreateParams.builder()
                .vaultId(vaultId)
                .name("GitHub access token")
                .auth(
                    CredentialAuthCreateParam.StaticBearer.builder()
                        .mcpServerUrl(mcpUrl)
                        .token(accessToken)
                        .build())
                .build());

# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://api.githubcopilot.com/mcp/"
access_token = ENV.fetch("GITHUB_TOKEN")

credential = client.beta.agents.vaults.credentials.create(
  vault_id,
  name: "GitHub access token",
  auth: {
    type: "static_bearer",
    mcp_server_url: mcp_url,
    token: access_token
  }
)

나중에 갱신할 수 있도록 자격 증명 ID를 credential_id로 저장하세요.

세션을 만들 때 저장한 ID를 vault_ids로 전달하세요. 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],
});

# Replace the illustrative IDs and URLs below with your own resource values.
mcp_url = "https://api.githubcopilot.com/mcp/"
vault_id = "vault_123"

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "tools": [
            {
                "type": "mcp",
                "server_label": "github",
                "transport": {
                    "type": "http",
                    "server_url": mcp_url,
                },
                "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=[vault_id],
)

// Replace the illustrative IDs and URLs below with your own resource values.
mcpUrl := "https://api.githubcopilot.com/mcp/"
vaultId := "vault_123"

session, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model: openai.String("gpt-6-astra"),
			Tools: []openai.AgentToolParamUnion{
				{
					OfParamMcp: &openai.AgentToolParamMcp{
						ServerLabel:      "github",
						Transport:        openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: mcpUrl}},
						AllowedTools:     []string{"search_issues", "issue_read"},
						Required:         openai.Bool(true),
						ConnectionOrigin: "service",
					},
				},
			},
		},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input:       openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Find open bugs reported in the last week.")},
		VaultIDs:    []string{vaultId},
	})
if err != nil {
	panic(err)
}

// Replace the illustrative IDs and URLs below with your own resource values.
String mcpUrl = "https://api.githubcopilot.com/mcp/";
String vaultId = "vault_123";

var session =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .addTool(
                            AgentToolParam.Mcp.builder()
                                .serverLabel("github")
                                .transport(
                                    McpTransportParam.Http.builder().serverUrl(mcpUrl).build())
                                .allowedTools(List.of("search_issues", "issue_read"))
                                .required(true)
                                .connectionOrigin(
                                    AgentToolParam.Mcp.ConnectionOrigin.of("service"))
                                .build())
                        .build())
                .environmentNone()
                .input("Find open bugs reported in the last week.")
                .vaultIds(List.of(vaultId))
                .build());

# Replace the illustrative IDs and URLs below with your own resource values.
mcp_url = "https://api.githubcopilot.com/mcp/"
vault_id = "vault_123"

session = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "github",
        transport: {
          type: "http",
          server_url: mcp_url
        },
        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: [vault_id]
)

Agents API는 서버 URL과 일치하는 자격 증명을 선택해요. 연결된 여러 자격 증명이 일치하면 MCP 도구의 credential_id로 하나를 선택하세요.

샌드박스에서 API 요청에 볼트 시크릿 사용하기 (Use vault secrets for API requests from a sandbox)

environment_variable 자격 증명을 사용해 OpenAI 호스팅 샌드박스에서 API 요청에 시크릿을 공급하세요. 샌드박스는 이름이 지정된 환경 변수에서 자리 표시자를 받아요. 실제 시크릿은 샌드박스 밖에 남아요.

이 워크플로는 openai_hosted 환경이 필요해요. 자체 호스팅 환경이나 애플리케이션에서 실행되는 함수 도구에는 자격 증명을 공급하지 않아요.

API 토큰 저장하기 (Store the API token)

위에서처럼 볼트를 만드세요. 그런 다음 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 대상에만 시크릿을 공급해요.

호스팅 세션에 볼트 연결하기 (Attach the vault to a hosted session)

세션을 만들 때 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 호출하기 (Call the API from the sandbox)

에이전트에 메시지를 보내 샌드박스에서 이 명령을 실행하게 하세요:

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

이 명령은 GITHUB_TOKEN에서 자리 표시자를 읽어요. 프록시는 api.github.com에 요청을 보내기 전에 그 자리 표시자를 실제 토큰으로 바꿔요. 성공적인 요청은 인증된 GitHub 사용자의 계정 세부 정보를 JSON으로 반환해요. 샌드박스 안에서 변수를 출력하면 토큰이 아니라 자리 표시자가 보여요.

자리 표시자를 HTTPS 요청 헤더에 변경 없이 전달하세요. 로컬 계산(예: 요청 서명)에는 실제 시크릿을 공급할 수 없어요. 그런 작업에는 자격 증명을 애플리케이션에 두고 함수 도구로 작업을 노출하세요.

OAuth 자격 증명 사용하기 (Use OAuth credentials)

애플리케이션이 프로바이더의 인증과 동의 흐름을 처리해요. 결과 그랜트를 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;

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

# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://mcp.example.com/mcp"
access_token = os.environ["OAUTH_ACCESS_TOKEN"]
expires_at = "2030-01-01T00:00:00Z"
token_endpoint = "https://auth.example.com/oauth/token"
client_id = "example-client-id"
refresh_token = os.environ["OAUTH_REFRESH_TOKEN"]

credential = client.beta.agents.vaults.credentials.create(
    vault_id,
    name="Example MCP OAuth credential",
    auth={
        "type": "mcp_oauth",
        "mcp_server_url": mcp_url,
        "access_token": access_token,
        "expires_at": expires_at,
        "refresh": {
            "token_endpoint": token_endpoint,
            "client_id": client_id,
            "refresh_token": refresh_token,
            "token_endpoint_auth": {"type": "none"},
        },
    },
)

// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
vaultId := "vault_123"
mcpUrl := "https://mcp.example.com/mcp"
accessToken := os.Getenv("OAUTH_ACCESS_TOKEN")
expiresAt := "2030-01-01T00:00:00Z"
tokenEndpoint := "https://auth.example.com/oauth/token"
clientId := "example-client-id"
refreshToken := os.Getenv("OAUTH_REFRESH_TOKEN")

credential, err := client.Beta.Agents.Vaults.Credentials.New(ctx,
	vaultId,
	openai.BetaAgentVaultCredentialNewParams{
		Name: "Example MCP OAuth credential",
		Auth: openai.CredentialAuthCreateParamUnion{
			OfParamMcpOAuth: &openai.CredentialAuthCreateParamMcpOAuth{
				McpServerURL: mcpUrl,
				AccessToken:  accessToken,
				ExpiresAt:    openai.String(expiresAt),
				Refresh: openai.CredentialAuthCreateParamMcpOAuthRefresh{
					TokenEndpoint:     tokenEndpoint,
					ClientID:          clientId,
					RefreshToken:      refreshToken,
					TokenEndpointAuth: openai.McpOAuthTokenEndpointAuthCreateParamUnion{OfParamNone: &openai.McpOAuthTokenEndpointAuthCreateParamNone{}},
				},
			},
		},
	})
if err != nil {
	panic(err)
}

// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
String vaultId = "vault_123";
String mcpUrl = "https://mcp.example.com/mcp";
String accessToken = System.getenv("OAUTH_ACCESS_TOKEN");
String expiresAt = "2030-01-01T00:00:00Z";
String tokenEndpoint = "https://auth.example.com/oauth/token";
String clientId = "example-client-id";
String refreshToken = System.getenv("OAUTH_REFRESH_TOKEN");

var credential =
    client
        .beta()
        .agents()
        .vaults()
        .credentials()
        .create(
            CredentialCreateParams.builder()
                .vaultId(vaultId)
                .name("Example MCP OAuth credential")
                .auth(
                    CredentialAuthCreateParam.McpOAuth.builder()
                        .mcpServerUrl(mcpUrl)
                        .accessToken(accessToken)
                        .expiresAt(expiresAt)
                        .refresh(
                            CredentialAuthCreateParam.McpOAuth.Refresh.builder()
                                .tokenEndpoint(tokenEndpoint)
                                .clientId(clientId)
                                .refreshToken(refreshToken)
                                .tokenEndpointAuthNone()
                                .build())
                        .build())
                .build());

# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://mcp.example.com/mcp"
access_token = ENV.fetch("OAUTH_ACCESS_TOKEN")
expires_at = "2030-01-01T00:00:00Z"
token_endpoint = "https://auth.example.com/oauth/token"
client_id = "example-client-id"
refresh_token = ENV.fetch("OAUTH_REFRESH_TOKEN")

credential = client.beta.agents.vaults.credentials.create(
  vault_id,
  name: "Example MCP OAuth credential",
  auth: {
    type: "mcp_oauth",
    mcp_server_url: mcp_url,
    access_token: access_token,
    expires_at: expires_at,
    refresh: {
      token_endpoint: token_endpoint,
      client_id: client_id,
      refresh_token: refresh_token,
      token_endpoint_auth: { type: "none" }
    }
  }
)

프로바이더가 요구하는 토큰 엔드포인트 인증 방법을 사용하세요. 예시는 none을 사용하고, client_secret_basic과 client_secret_post도 지원돼요. 필드는 자격 증명 생성 레퍼런스를 참고하세요.

만료된 토큰을 갱신할 수 없으면 유효한 교체 토큰을 공급하세요. 토큰 만료가 자격 증명이나 볼트를 삭제하지는 않아요.

자격 증명 회전 또는 제거하기 (Rotate or remove credentials)

자격 증명 갱신으로 시크릿을 바꾸되 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,
      },
    },
  }
);

# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
credential_id = "cred_123"
vault_id = "vault_123"
access_token = os.environ["OAUTH_ACCESS_TOKEN"]
expires_at = "2030-01-01T00:00:00Z"

credential = client.beta.agents.vaults.credentials.update(
    credential_id,
    vault_id=vault_id,
    auth={
        "type": "mcp_oauth",
        "access_token": access_token,
        "expires_at": expires_at,
    },
)

// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
vaultId := "vault_123"
credentialId := "cred_123"
accessToken := os.Getenv("OAUTH_ACCESS_TOKEN")
expiresAt := "2030-01-01T00:00:00Z"

credential, err := client.Beta.Agents.Vaults.Credentials.Update(ctx,
	vaultId,
	credentialId,
	openai.BetaAgentVaultCredentialUpdateParams{
		Auth: openai.CredentialAuthRotateParamUnion{
			OfParamMcpOAuth: &openai.CredentialAuthRotateParamMcpOAuth{
				AccessToken: openai.String(accessToken),
				ExpiresAt:   openai.String(expiresAt),
			},
		},
	})
if err != nil {
	panic(err)
}

// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
String credentialId = "cred_123";
String vaultId = "vault_123";
String accessToken = System.getenv("OAUTH_ACCESS_TOKEN");
String expiresAt = "2030-01-01T00:00:00Z";

var credential =
    client
        .beta()
        .agents()
        .vaults()
        .credentials()
        .update(
            CredentialUpdateParams.builder()
                .credentialId(credentialId)
                .vaultId(vaultId)
                .auth(
                    CredentialAuthRotateParam.McpOAuth.builder()
                        .accessToken(accessToken)
                        .expiresAt(expiresAt)
                        .build())
                .build());

# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
credential_id = "cred_123"
vault_id = "vault_123"
access_token = ENV.fetch("OAUTH_ACCESS_TOKEN")
expires_at = "2030-01-01T00:00:00Z"

credential = client.beta.agents.vaults.credentials.update(
  credential_id,
  vault_id: vault_id,
  auth: {
    type: "mcp_oauth",
    access_token: access_token,
    expires_at: expires_at
  }
)

교체 토큰이 만료되는 경우 expires_at을 포함하세요. 만료 없이 새 접근 토큰을 공급하면 저장된 만료가 지워지고, 명시적 null도 지워요.

환경 자격 증명에서는 auth.type: "environment_variable"과 교체 auth.secret_value를 POST /v1/vaults/{vault_id}/credentials/{credential_id}로 보내세요. 교체본을 사용하려면 새 세션을 만드세요. 볼트를 갱신해도 기존 샌드박스에 이미 구성된 자격 증명은 바뀌지 않아요.

secret_name이나 networking을 바꾸려면 새 자격 증명을 만드세요.

더 이상 필요 없으면 자격 증명을 삭제하세요. 볼트를 삭제하면 볼트와 그 모든 자격 증명이 제거돼요.

저장된 자격 증명을 삭제해도 프로바이더에서 원래 토큰을 폐기하거나 실행 중인 세션을 중지하지 않아요. 애플리케이션이 프로바이더 측 폐기와 세션 취소를 처리해요.

더 알아보기 (Learn more)

• MCP 연결 가이드에서 자격 증명 경계와 인증 옵션을 확인하세요.
• 샌드박스 보안에서 서드파티 자격 증명을 안전하게 관리하는 방법을 확인하세요.