Una bóveda almacena credenciales fuera de las instrucciones y la configuración de tu agente. Vincúlala a una sesión mediante vault_ids para que la sesión pueda usar esas credenciales.
Elige el tipo de credencial según el origen de la solicitud:
| Solicitud |
Tipo de credencial |
Cómo usa la credencial la sesión |
| Conexión MCP desde OpenAI |
static_bearer o mcp_oauth |
OpenAI se autentica ante el servidor MCP configurado. |
| Solicitud a una API desde un sandbox alojado en OpenAI |
environment_variable |
El código usa una variable de entorno que contiene un marcador de posición. Un proxy de red sustituye el marcador por el secreto en las solicitudes a los hosts autorizados. |
Por ejemplo, un sandbox puede usar un secreto de una bóveda para llamar a la API REST de GitHub. Sigue los pasos de Usar secretos de una bóveda para enviar solicitudes a una API desde un sandbox.
Al consultar una bóveda o una credencial, la respuesta no incluye los valores secretos. Para otras conexiones MCP, consulta las opciones de autenticación de MCP.
Para una clave de aplicación restringida, otorga estos permisos:
api.vaults.read para listar y consultar bóvedas y credenciales.api.vaults.write para crearlas, actualizarlas o eliminarlas.
Usa tu cliente de API, la URL del servidor MCP (mcp_url) y un token de acceso para ese servidor (access_token). Los ejemplos usan herramientas de GitHub.
Primero, crea una bóveda:
1
2
3
4
5
6const vault = await client.beta.agents.vaults.create({
name: "GitHub credentials",
metadata: {
external_user_id: "user_123",
},
});
1
2
3vault = client.beta.agents.vaults.create(
name="GitHub credentials", metadata={"external_user_id": "user_123"}
)
1
2
3
4
5
6
7
8vault, 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)
}
1
2
3
4
5
6
7
8
9
10
11
12
13var 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());
1
2
3
4vault = client.beta.agents.vaults.create(
name: "GitHub credentials",
metadata: { external_user_id: "user_123" }
)
Guarda el ID de la bóveda como vault_id y luego agrega el token. El campo mcp_server_url vincula la credencial a ese servidor:
1
2
3
4
5
6
7
8
9
10
11
12
13// 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,
},
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14# 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,
},
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19// 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)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// 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());
1
2
3
4
5
6
7
8
9
10
11
12
13
14# 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
}
)
Guarda el ID de la credencial como credential_id para futuras actualizaciones.
Pasa el ID de la bóveda en vault_ids al crear una sesión. Usa la misma URL del servidor en la configuración de MCP:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// 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],
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25# 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],
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// 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)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29// 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());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28# 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]
)
La API de agentes selecciona una credencial cuya URL coincide con la del servidor. Si varias credenciales vinculadas coinciden, asigna el ID de la que quieras usar al campo credential_id de la herramienta MCP.
Usa una credencial de tipo environment_variable para proporcionar un secreto en las solicitudes a una API desde un sandbox alojado en OpenAI. El sandbox recibe un marcador de posición en la variable de entorno especificada. El secreto real permanece fuera del sandbox.
Este flujo de trabajo requiere un entorno de tipo openai_hosted. No proporciona credenciales a entornos que alojas por tu cuenta ni a herramientas de función que ejecuta tu aplicación.
Crea una bóveda como se muestra arriba. Luego, envía una solicitud de creación de credencial a POST /v1/vaults/{vault_id}/credentials con estos campos:
| Campo |
Valor para un token de la API de GitHub |
name |
GitHub API token |
auth.type |
environment_variable |
auth.secret_name |
GITHUB_TOKEN |
auth.secret_value |
El token que tu aplicación lee de una variable de entorno secreta. |
auth.networking.type |
limited |
auth.networking.allowed_hosts |
["api.github.com"] |
secret_name identifica la variable de entorno que lee el código del sandbox. secret_value contiene la credencial real. No la incluyas en prompts, archivos de código fuente ni registros.
Especifica los nombres exactos de los hosts en allowed_hosts, sin esquema, ruta, puerto ni comodines. El proxy solo proporciona secretos a destinos HTTPS que usan el puerto 443 o el 8443.
Incluye los siguientes campos junto con agent al crear una sesión. Reemplaza vault_123 por el ID de la bóveda que devolvió la API:
12345678910{
"vault_ids": ["vault_123"],
"environment": {
"type": "openai_hosted",
"network": {
"access": "restricted",
"allowed_domains": ["api.github.com"]
}
}
}
Las dos listas de hosts tienen funciones distintas. allowed_domains permite que el sandbox se conecte a un host. El campo allowed_hosts de la credencial permite que el proxy proporcione el secreto a ese host.
Si el acceso a la red está restringido, incluye en allowed_domains todos los hosts de cada credencial. No establezcas network.access en disabled para una sesión con credenciales de entorno.
Cada credencial de entorno vinculada debe tener un secret_name único. No definas ese mismo nombre en environment.env.
Envía un mensaje al agente y pídele que ejecute este comando en el sandbox:
curl https://api.github.com/user \
-H "Authorization: Bearer $GITHUB_TOKEN"
El comando lee el marcador de posición de GITHUB_TOKEN. El proxy lo reemplaza por el token real antes de enviar la solicitud a api.github.com. Si la solicitud tiene éxito, la respuesta contiene los datos de la cuenta del usuario autenticado de GitHub en formato JSON. Si imprimes la variable dentro del sandbox, solo verás el marcador de posición.
Pasa el marcador de posición sin modificarlo en el encabezado de la solicitud HTTPS. El marcador no permite obtener el secreto real para operaciones locales como firmar una solicitud. Para esas tareas, conserva la credencial en tu aplicación y expón la operación mediante una herramienta de función.
Tu aplicación gestiona el flujo de autorización y consentimiento del proveedor. Almacena la autorización obtenida con auth.type: "mcp_oauth". Si sabes cuándo vence el token de acceso, indica ese momento en expires_at con una marca de tiempo en formato RFC 3339.
El siguiente ejemplo usa valores del flujo OAuth de tu proveedor. Incluye refresh para que la API de agentes pueda renovar el token:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// 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",
},
},
},
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26# 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"},
},
},
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31// 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)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34// 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());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26# 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" }
}
}
)
Usa el método de autenticación que exige tu proveedor para el punto de acceso de tokens. El ejemplo usa none. También se admiten client_secret_basic y client_secret_post. Consulta los campos en la referencia de creación de credenciales.
Si no es posible renovar un token vencido, reemplázalo por uno válido. El vencimiento del token no elimina la credencial ni su bóveda.
Actualiza una credencial para reemplazar su secreto sin cambiar su ID ni su tipo de autenticación. En el caso de las credenciales MCP, la URL del servidor también se mantiene. Para OAuth, usa los valores de vault_id y credential_id que guardaste, junto con el nuevo token y su fecha de vencimiento:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20// 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,
},
},
}
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16# 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,
},
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// 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)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23// 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());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16# 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
}
)
Incluye expires_at si el nuevo token tiene fecha de vencimiento. Si proporcionas un nuevo token de acceso sin fecha de vencimiento, se borra la fecha almacenada. También puedes borrarla si envías null de forma explícita.
Para una credencial de entorno, envía auth.type: "environment_variable" y el nuevo valor de auth.secret_value a POST /v1/vaults/{vault_id}/credentials/{credential_id}. Crea una sesión nueva para usar el nuevo secreto. Actualizar la bóveda no modifica la credencial ya configurada en un sandbox existente.
Para cambiar secret_name o networking, crea una credencial nueva.
Elimina una credencial cuando ya no la necesites. Elimina una bóveda para borrar tanto la bóveda como todas sus credenciales.
Eliminar las credenciales almacenadas no revoca los tokens originales ante sus proveedores ni detiene una sesión en curso. Tu aplicación se encarga de revocar los tokens ante el proveedor y de cancelar la sesión.
