Autenticar con vaults

Los "vaults" (bóvedas) y las credenciales son primitivas de autenticación que te permiten registrar credenciales para servicios de terceros una sola vez y referenciarlas por ID al crear una sesión. Esto significa que no necesitas ejecutar tu propio almacén de secretos, transmitir tokens en cada llamada ni perder el rastro de en nombre de qué usuario final actuó un agente.

La referencia al vault es un parámetro por sesión, por lo que puedes gestionar tu producto con la granularidad del recurso agent y tus usuarios con la granularidad del recurso session.



Crear un vault

Un vault es la colección de credentials asociadas a un usuario final. Asígnale un display_name y, opcionalmente, etiquétalo con metadata para poder mapearlo de vuelta 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)
echo "$VAULT_ID"  # "vlt_01ABC..."

La respuesta es el registro completo del vault:

{
  "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

Se admiten dos categorías de credenciales:

• Credenciales MCP (mcp_oauth, static_bearer): cada credencial se identifica mediante un mcp_server_url. Cuando el agente se conecta a un servidor en esa URL durante el tiempo de ejecución de la sesión, el token se inyecta automáticamente.
• Variables de entorno (environment_variable): cada credencial se identifica mediante un secret_name (el nombre de la variable de entorno) y se almacena en el sandbox como un marcador de posición opaco. Cuando el agente inicia una solicitud saliente, el marcador de posición opaco se sustituye por el secreto real en la salida (egress). El agente nunca ve el valor del secreto. Usa esto para cualquier servicio que se autentique mediante una variable de entorno, como CLIs, SDKs o llamadas directas a la API.

Los valores reales de las credenciales que proporcionas (token, access_token, refresh_token, client_secret, secret_value) se tratan como campos sensibles de solo escritura y nunca se devuelven en las respuestas de la API.

Las credenciales se almacenan tal como se proporcionan y no se validan hasta el tiempo de ejecución de la sesión. Una credencial inválida se manifiesta como un error de autenticación o un error downstream durante la sesión, el cual se emite pero no impide que la sesión continúe.

Restricciones:

• Clave única por vault. mcp_server_url (credenciales MCP) y secret_name (credenciales de variable de entorno) deben ser únicos entre las credenciales activas de un vault. Crear un duplicado devuelve un 409.
• Las claves son inmutables. Para cambiar mcp_server_url o secret_name, archiva la credencial y crea una nueva.
• Máximo 20 credenciales por vault.



Referenciar el vault al crear una sesión

Pasa vault_ids al crear una sesión:

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --vault-id "$VAULT_ID" \
  --title "Alice's Slack digest" \
  --transform id --raw-output)

Comportamiento en tiempo de ejecución:

• Cuando ninguna credencial MCP coincide por mcp_server_url, la conexión se intenta sin autenticación y generará un error si el servidor requiere autenticación.
• Cuando varios vaults contienen una credencial coincidente, gana el primer vault con una coincidencia.
• En sesiones multiagente, las credenciales del vault se aplican a todos los hilos. Un agente cuya propia definición declara el servidor MCP coincidente se autentica con estas credenciales. Consulta Conectar agentes a servidores MCP.



Rotar una credencial

Los valores de secreto, display_name y (en credenciales de variable de entorno) injection_location se pueden actualizar. Las actualizaciones de injection_location se fusionan por campo, como se describe en la pestaña Variable de entorno de Agregar una credencial. Para una sesión en ejecución, una actualización de injection_location se propaga de la misma manera que una rotación de secreto: las credenciales de la sesión se vuelven a resolver sin reiniciar, como se describe en Ciclo de vida de las credenciales, y las ubicaciones actualizadas se aplican a las solicitudes salientes posteriores de la sesión. Los campos estructurales (mcp_server_url, secret_name, token_endpoint, client_id) quedan bloqueados después de la creación. Para cambiarlos, archiva la credencial y crea una nueva.

ant beta:vaults:credentials update \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" <<'YAML'
auth:
  type: mcp_oauth
  access_token: xoxp-new-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    refresh_token: xoxe-1-new-...
YAML



Ciclo de vida de las credenciales

Las credenciales se vuelven a resolver periódicamente, tanto durante una sesión como durante el ciclo de vida del vault. Esto garantiza que la rotación, el archivado o la eliminación de credenciales se propague a las sesiones en ejecución sin necesidad de reiniciar.

Para recibir una notificación si una credencial se archiva, se elimina o falla al actualizarse, puedes suscribirte a los webhooks de vault y credencial asociados con esos cambios de ciclo de vida.

Para las credenciales mcp_oauth, la re-resolución también actualiza el token de acceso si ha expirado. Si la actualización falla, se emite un evento vault_credential.refresh_failed.



Diagnosticar un fallo de actualización de OAuth

Para diagnosticar por qué falló una actualización, llama a POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate (o client.beta.vaults.credentials.mcp_oauth_validate(...) en el SDK). Esto te permite decidir cómo manejar el fallo; la acción correcta depende del tipo de error.

El status de nivel superior te indica qué hacer a continuación:

• valid: el token funciona; no se necesita ninguna acción.
• invalid: el grant ya no existe o el servidor OAuth rechazó la actualización con un 4xx. Solicita al usuario final que vuelva a autorizar.
• unknown: un error transitorio (5xx, 429 o fallo de red). Espera y vuelve a intentarlo.

ant beta:vaults:credentials mcp-oauth-validate \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" \
  --transform status --raw-output  # "valid", "invalid", or "unknown"

La respuesta es un objeto vault_credential_validation. mcp_probe incluye el paso del handshake MCP que falló; refresh incluye el resultado del intento de actualización.

{
  "type": "vault_credential_validation",
  "credential_id": "vcrd_01ABC...",
  "vault_id": "vlt_01XYZ...",
  "validated_at": "2026-04-29T17:12:00Z",
  "has_refresh_token": false,
  "status": "invalid",
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  },
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  }
}



Otras operaciones

• Listar vaults o credenciales: Paginado, los más recientes primero. Los registros archivados se excluyen de forma predeterminada (pasa include_archived=true para incluirlos).
• Archivar un vault: POST /v1/vaults/{id}/archive. Se propaga en cascada a todas las credenciales. Los secretos se purgan; los registros se conservan para auditoría. Las sesiones futuras que referencien este vault fallan; las sesiones en ejecución continúan.
• Archivar una credencial: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Purga la carga útil del secreto; la clave de la credencial (mcp_server_url o secret_name) permanece visible y queda liberada para una credencial de reemplazo.
• Eliminar un vault o credencial: Eliminación definitiva. El registro no se conserva. Usa archivar si necesitas un registro de auditoría.