Autenticar con vaults
Registra credenciales por usuario al crear sesiones.
Los vaults 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 con un usuario final. Dale un display_name y, opcionalmente, etiquétalo con metadata para que puedas mapearlo de vuelta a tus propios registros de usuario.
vault = client.beta.vaults.create(
display_name="Alice",
metadata={"external_user_id": "usr_abc123"},
)
print(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 indexa por unmcp_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 indexa por unsecret_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. El agente nunca ve el valor del secreto. Usa esto para cualquier servicio que se autentique a través de 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.
Usa mcp_oauth cuando el servidor MCP utiliza OAuth 2.0. Si proporcionas un bloque refresh, Anthropic actualiza el token de acceso en tu nombre cuando expira.
El campo refresh.token_endpoint_auth.type indica cómo autenticar la llamada de actualización:
none: cliente públicoclient_secret_basic: autenticación HTTP Basic con el secreto del clienteclient_secret_post: secreto del cliente en el cuerpo del POST
credential = client.beta.vaults.credentials.create(
vault_id=vault.id,
display_name="Alice's Slack",
auth={
"type": "mcp_oauth",
"mcp_server_url": "https://mcp.slack.com/mcp",
"access_token": "xoxp-...",
"expires_at": "2099-12-31T23:59:59Z",
"refresh": {
"token_endpoint": "https://slack.com/api/oauth.v2.user.access",
"client_id": "1234567890.0987654321",
"scope": "channels:read chat:write",
"refresh_token": "xoxe-1-...",
"token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."},
},
},
)Establece refresh.token_endpoint en el endpoint de token del flujo OAuth que emitió el token de actualización, ya que Anthropic envía cada solicitud de actualización a esa URL y el campo no se puede cambiar después de crear la credencial.
Usa static_bearer cuando el servidor MCP acepta un token bearer fijo (clave de API, token de acceso personal o similar). No se necesita flujo de actualización.
bearer_credential = client.beta.vaults.credentials.create(
vault_id=vault.id,
display_name="Linear API key",
auth={
"type": "static_bearer",
"mcp_server_url": "https://mcp.linear.app/mcp",
"token": "lin_api_your_linear_key",
},
)Usa environment_variable para autenticarte en servicios externos a través de una variable de entorno, como CLIs, SDKs o llamadas directas a la API. Las credenciales de variables de entorno funcionan para clientes que envían el valor del secreto textualmente en una solicitud saliente, así que verifica los criterios de elegibilidad del cliente en esta pestaña antes de configurar una.
El array networking.allowed_hosts controla para qué hosts salientes se puede sustituir el secreto. Usa "type": "limited" con una lista específica, o "type": "unrestricted" si el llamador alcanza dominios que no puedes enumerar de antemano.
Se recomienda encarecidamente limitar los dominios por motivos de seguridad, y evita que tu clave se comparta alguna vez con hosts no autorizados.
El campo opcional injection_location delimita dónde se sustituye el secreto; la semántica completa sigue al ejemplo.
env_credential = client.beta.vaults.credentials.create(
vault_id=vault.id,
display_name="Notion API key for sandbox",
auth={
"type": "environment_variable",
"secret_name": "NOTION_API_KEY",
"secret_value": "ntn_your-secret-here",
"networking": {
"type": "limited",
"allowed_hosts": ["api.notion.com"],
},
"injection_location": {"header": True},
},
)
if env_credential.auth.type == "environment_variable":
location = env_credential.auth.injection_location
print(f"header: {location.header}, body: {location.body}") # header: True, body: FalseLas cargas útiles de las solicitudes a menudo se ensamblan a partir del contenido con el que el agente está trabajando, por lo que el cuerpo de la solicitud es la superficie de exposición más amplia. La mayoría de los servicios leen una clave de API desde un encabezado de solicitud, por lo que habilitar solo header es la configuración más restringida. Delimita la sustitución a los valores de los encabezados de solicitud para esa credencial.
El injection_location de la credencial controla en qué partes de una solicitud saliente se sustituye el secreto. Es un objeto opcional, hermano de networking, con dos campos booleanos: header (encabezados de solicitud) y body (cuerpo de solicitud). injection_location es independiente de networking.allowed_hosts: allowed_hosts delimita para qué hosts se sustituye el secreto, y injection_location delimita en qué partes de la solicitud se sustituye.
injection_location se comporta de manera diferente al crear y al actualizar:
| Operación | Comportamiento de injection_location |
|---|---|
| Crear credencial | Si proporcionas el objeto, cualquier campo que omitas dentro de él toma el valor predeterminado false: {"header": true} crea una credencial solo de encabezado. Omite el objeto por completo y ambas ubicaciones quedan habilitadas. |
| Actualizar credencial | Los campos se fusionan individualmente: {"body": false} deshabilita la sustitución en el cuerpo y deja header sin cambios. |
Una credencial debe tener al menos una ubicación habilitada, por lo que una creación o actualización que deshabilitaría ambas ubicaciones devuelve un error 400. Pasar un null explícito para el objeto injection_location o para cualquiera de los campos también devuelve un error 400 ("omite el campo en su lugar"). La respuesta siempre devuelve ambos campos con sus valores resueltos.
Un marcador de posición en una ubicación deshabilitada no se sustituye ni se elimina. La solicitud se envía al tercero con la cadena literal del marcador de posición opaco en esa ubicación. Si una solicitud llega al tercero conteniendo la cadena literal del marcador de posición, o bien esa ubicación está deshabilitada para la credencial o el host de destino no está cubierto por el networking.allowed_hosts de la credencial.
La sustitución ocurre en la salida, no dentro del sandbox. Cualquier cosa que procese la credencial localmente ve el marcador de posición opaco, no el valor real: los clientes que validan el formato de la credencial al inicio pueden rechazarla, y los clientes que calculan una firma de solicitud a partir del secreto (por ejemplo, AWS SigV4) producen una firma inválida. Las credenciales de variables de entorno funcionan para clientes que envían el valor del secreto textualmente en una solicitud saliente, en una ubicación que el injection_location de la credencial habilita.
La sustitución es solo saliente. Si un cliente usa el secreto almacenado para obtener un token de sesión (por ejemplo, una concesión de credenciales de cliente OAuth), el token devuelto llega al sandbox sin redactar. Para flujos basados en intercambio, realiza el intercambio tú mismo y almacena el token resultante en el vault en su lugar.
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 aparece como un error de autenticación o de flujo descendente durante la sesión, que se emite pero no impide que la sesión continúe.
Restricciones:
- Clave única por vault.
mcp_server_url(credenciales MCP) ysecret_name(credenciales de variables de entorno) deben ser únicos entre las credenciales activas en un vault. Crear un duplicado devuelve un 409. - Las claves son inmutables. Para cambiar
mcp_server_urlosecret_name, archiva la credencial y crea una nueva. - Máximo 20 credenciales por vault.
Referenciar el vault al crear la sesión
Pasa vault_ids al crear una sesión:
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
vault_ids=[vault.id],
title="Alice's Slack digest",
)Comportamiento en tiempo de ejecución:
- Cuando ninguna credencial MCP coincide por
mcp_server_url, la conexión se intenta sin autenticación y dará error si el servidor requiere autenticación. - Cuando múltiples vaults contienen una credencial coincidente, gana el primer vault con una coincidencia.
- En sesiones multiagente, las credenciales del vault se aplican a cada hilo. 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 secretos, display_name y (en credenciales de variables de entorno) injection_location pueden actualizarse. Las actualizaciones de injection_location se fusionan por campo, como se describe en la pestaña Environment variable 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 un reinicio, 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.
client.beta.vaults.credentials.update(
credential.id,
vault_id=vault.id,
auth={
"type": "mcp_oauth",
"access_token": "xoxp-new-...",
"expires_at": "2099-12-31T23:59:59Z",
"refresh": {"refresh_token": "xoxe-1-new-..."},
},
)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 propaguen a las sesiones en ejecución sin un reinicio.
Para recibir notificaciones si una credencial se archiva, se elimina o no se puede actualizar, puedes suscribirte a los webhooks de vault y credencial asociados con esos cambios de ciclo de vida.
| Evento | Disparador |
|---|---|
vault.archived | Vault archivado. También se emite un evento vault_credential.archived para cada credencial subyacente. |
vault.deleted | Vault eliminado. También se emite un evento vault_credential.deleted para cada credencial subyacente. |
vault_credential.archived | Credencial archivada, ya sea directamente o como resultado del archivado del vault. |
vault_credential.deleted | Credencial eliminada, ya sea directamente o como resultado de la eliminación del vault. |
vault_credential.refresh_failed | Una credencial mcp_oauth no se puede actualizar (token de actualización inválido, o error irrecuperable del servidor OAuth). |
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 adecuada 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: la concesión 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 reintenta.
validation = client.beta.vaults.credentials.mcp_oauth_validate(
credential.id,
vault_id=vault.id,
)
print(validation.status) # "valid", "invalid", or "unknown"La respuesta es un objeto vault_credential_validation. mcp_probe incluye el paso fallido del handshake MCP; refresh incluye el resultado de la actualización intentada.
{
"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=truepara 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_urlosecret_name) permanece visible y queda liberada para una credencial de reemplazo. - Eliminar un vault o credencial: Eliminación permanente. El registro no se conserva. Usa el archivado si necesitas un rastro de auditoría.
Was this page helpful?