Autenticarse con bóvedas

Las bóvedas y credenciales son primitivos de autenticación que te permiten registrar credenciales para servicios de terceros una sola vez y hacer referencia a ellas por ID al crear una sesión. Esto significa que no necesitas ejecutar tu propio almacén de secretos, transmitir tokens en cada llamada, o perder el seguimiento de qué usuario final un agente actuó en nombre de.

La referencia de bóveda es un parámetro por sesión, por lo que puedes gestionar tu producto a nivel de agente y tus usuarios a nivel de sesión.

Crear una bóveda

Una bóveda es la colección de credentials asociadas a un usuario final. Dale un display_name y opcionalmente etiquétala con metadata para que puedas asignarla a tus propios registros de usuario.

VAULT_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)

La respuesta es el registro de bóveda completo:

{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}

Agregar una credencial

Cada credencial se vincula a una única mcp_server_url. Cuando el agente se conecta a un servidor MCP en tiempo de ejecución de sesión, la API compara la URL del servidor con las credenciales activas en la bóveda referenciada e inyecta el token.

Las credenciales se almacenan tal como se proporcionan y no se validan hasta el tiempo de ejecución de la sesión. Un token incorrecto aparece como un error de autenticación MCP durante la sesión, que se emite pero no bloquea que la sesión continúe.

Restricciones:

• Una credencial activa por mcp_server_url por bóveda. Crear una segunda credencial para la misma URL devuelve un 409.
• mcp_server_url es inmutable. Para apuntar a un servidor diferente, archiva esta credencial y crea una nueva.
• Máximo 20 credenciales por bóveda. Esto coincide con la cantidad máxima de servidores MCP por agente.

Rotar una credencial

Solo la carga útil secreta y algunos campos de metadatos son mutables. mcp_server_url, token_endpoint y client_id están bloqueados después de la creación.

Hacer referencia a la bóveda al crear la sesión

Pasa vault_ids al crear una sesión:

Comportamiento en tiempo de ejecución:

• Las credenciales se resuelven periódicamente durante la sesión, por lo que una rotación o archivo se propaga a sesiones en ejecución sin necesidad de reinicio.
• Cuando una bóveda no tiene credencial para el servidor MCP, la conexión se intenta sin autenticación y produce un error.
• Cuando múltiples bóvedas cubren el servidor MCP, la primera bóveda con una coincidencia gana.

Otras operaciones

• Listar bóvedas o credenciales: Paginado, más reciente primero. Los registros archivados se excluyen por defecto (pasa include_archived=true para incluirlos).
• Archivar una bóveda: POST /v1/vaults/{id}/archive. Se propaga en cascada a todas las credenciales. Los secretos se purgan; los registros se retienen para auditoría. Las sesiones futuras que hagan referencia a esta bóveda fallan; las sesiones en ejecución continúan.
• Archivar una credencial: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Purga la carga útil secreta; mcp_server_url permanece visible. Libera mcp_server_url para una credencial de reemplazo.
• Eliminar una bóveda o credencial: Eliminación dura. El registro no se retiene. Usa archivo si necesitas un rastro de auditoría.