For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal

Sugerencias

API de agentes

SDK de agentes

ChatKit

API Dashboard
Probar ChatGPT

Bóvedas

Almacena credenciales MCP y vincúlalas a sesiones de agentes.

Una bóveda almacena credenciales para conexiones MCP desde OpenAI. Vincúlala a una sesión para que el agente pueda usar herramientas autenticadas sin recibir los valores secretos.

Las bóvedas admiten tokens de portador y concesiones OAuth existentes. Para conexiones desde tu entorno, usa las otras opciones de autenticación MCP.

Permisos

Para una clave de aplicación restringida, otorga:

  • api.vaults.read para listar y obtener bóvedas y credenciales.
  • api.vaults.write para crearlas, actualizarlas o eliminarlas.

Crea y usa una bóveda

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:

Crea una bóveda
const vault = await client.beta.agents.vaults.create({
  name: "GitHub credentials",
  metadata: {
    external_user_id: "user_123",
  },
});

Guarda su ID como vault_id y luego agrega el token. mcp_server_url vincula la credencial a ese servidor:

Almacena un token de portador
// 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,
  },
});

Guarda el ID de la credencial como credential_id para futuras actualizaciones.

Pasa el ID guardado en vault_ids al crear una sesión. Usa la misma URL del servidor en la configuración de MCP:

Vincula la bóveda a una sesión
// 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],
});

La API de agentes selecciona una credencial que coincida con la URL del servidor. Si varias credenciales vinculadas coinciden, establece credential_id en la herramienta MCP para seleccionar una. Al obtener una bóveda o credencial, no se devuelven sus valores secretos.

Usa credenciales OAuth

Tu aplicación se encarga del flujo de autorización y consentimiento del proveedor. Almacena la concesión resultante con auth.type: "mcp_oauth". Si conoces el vencimiento del token de acceso, establece expires_at con ese valor en forma de marca de tiempo RFC 3339.

El siguiente ejemplo usa valores del flujo OAuth de tu proveedor. Incluye refresh para permitir que la API de agentes renueve el token:

Almacena una concesión 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",
      },
    },
  },
});

Usa el método de autenticación del punto de acceso de tokens que requiera tu proveedor. 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 se puede renovar un token vencido, proporciona uno válido como reemplazo. El vencimiento del token no elimina la credencial ni su bóveda.

Rota o elimina credenciales

Actualiza una credencial para reemplazar su token sin cambiar su ID, tipo de autenticación ni URL del servidor. Para OAuth, usa los valores guardados de vault_id y credential_id junto con el token de reemplazo y su vencimiento:

Rota un token 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,
      },
    },
  }
);

Incluye expires_at si el token de reemplazo tiene vencimiento. Proporcionar un nuevo token de acceso sin vencimiento borra el vencimiento almacenado; un valor null explícito también lo borra.

Elimina una credencial cuando ya no la necesites. Elimina una bóveda para quitar la bóveda y todas sus credenciales.

Eliminar las credenciales almacenadas no revoca los tokens originales con sus proveedores ni detiene una sesión en ejecución. Tu aplicación se encarga de la revocación del lado del proveedor y de la cancelación de sesiones.