Vault Integration for Secure Credential Handling in Claude Agents: A CWC Workshops Implementation Guide

Vault integration enables Claude agents to securely access credentials at runtime by attaching vault identifiers to sessions, eliminating hard-coded secrets from source code while leveraging the Claude-Managed-Platform's built-in secret lifecycle management.

The anthropics/cwc-workshops repository provides a production-ready framework for deploying Claude agents in secure enterprise environments. One of its core architectural features is Vault integration for secure credential handling in Claude agents, which isolates sensitive authentication data from application code and injects credentials dynamically during session initialization.

Architectural Overview of Vault Integration

The secure credential system operates through a four-stage pipeline that separates secret storage from application logic. Understanding this flow is essential for implementing robust security in production Claude agents.

The Vault Credential Lifecycle

The implementation follows a strict isolation pattern:

1. Define – Create a named vault via the UI or programmatically using the vaults API
2. Store – Insert static-bearer tokens or other secret types into the vault using creds.create or creds.update
3. Attach – Include vault_ids in the session creation payload to bind credentials to a specific agent runtime
4. Access – The Claude-Managed-Platform (CMA) automatically injects the credential into the agent's environment, accessible via env("VAULT_ID")

This architecture ensures that credentials exist only in encrypted vault storage and the ephemeral runtime environment, never appearing in source control or environment configuration files.

Core Components

The system comprises three primary integration points:

• Next.js Session API – Handles dynamic attachment of vaults to new sessions via the vault_ids parameter
• Vault Management UI – Provides user interface components for selecting and configuring vault access during evaluation setup
• Python SDK Integration – Offers programmatic vault creation and credential rotation for agent-battle scenarios and automated deployments

Implementing Vault Support in Next.js Applications

The production-ready Next.js starter demonstrates how to conditionally attach vault credentials when initiating agent sessions.

Session API Configuration

In production-ready-agent/starter/app/api/sessions/route.ts, the session creation endpoint dynamically constructs the request payload to include vault identifiers only when configured:

export async function POST(req: Request) {
  const { agent, env, resources, mcp } = await req.json();

  // `ids.vault` is populated only when the UI selected a vault
  const body = {
    agent,
    env,
    resources,
    ...(mcp && ids.vault ? { vault_ids: [ids.vault] } : {}), // ← Vault attached here
  };

  const response = await fetch(`${CMA_API}/sessions/create`, {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify(body),
  });

  return new Response(await response.text());
}

The conditional spread syntax ensures that vault_ids appears in the request body only when an MCP server configuration is present and a vault has been selected, maintaining backward compatibility for sessions that do not require external credentials.

UI Components for Vault Selection

The production-ready-agent/starter/components/NewEvaluationModal.tsx provides the interface for attaching vaults to evaluation sessions:

<FormField
  name="vault"
  label="Vault"
  hint="Attach vault credentials for ticket lookup"
  options={vaultList.map(v => ({ label: v.display_name, value: v.id }))}
  type="select"
/>

When users select a vault through this modal, the chosen ID propagates through the application state to the session API, completing the secure credential chain from user selection to runtime injection.

SDK Wrapper Implementation

The production-ready-agent/starter/lib/anthropic.ts file contains the SDK wrapper that reads the VAULT_ID environment variable, enabling agents to reference the injected credentials at runtime:

// The SDK wrapper accesses vault credentials via:
const vaultId = env("VAULT_ID");

Python Implementation for Agent Credentials

The agent-battle/my_agent.py file demonstrates low-level vault management for Python-based agents requiring programmatic credential control.

Low-Level Vault Management

The _ensure_vault_credential() function handles the complete lifecycle of vault discovery, creation, and credential rotation:

def _session_vault_ids():
    """Return a list of vault IDs to attach to a CMA session."""
    return _cache.get("vault_ids")  # populated by _ensure_vault_credential()

def _ensure_vault_credential(client, cache, mcp_server_url, token):
    """Create or refresh a static‑bearer credential inside a CMA vault."""
    vaults_api = client.beta.vaults
    vault_cache = cache.setdefault("vault", {})

    # Find or create a named vault

    vault_id = vault_cache.get("_vault_id")
    if not vault_id:
        existing = next((v for v in vaults_api.list() if v.display_name == "agent-battle"), None)
        vault_id = existing.id if existing else vaults_api.create(display_name="agent-battle").id
        vault_cache["_vault_id"] = vault_id

    # Create or update the static_bearer credential

    creds = vaults_api.credentials
    cred = next((c for c in creds.list(vault_id) if c.name == "static_bearer"), None)
    if cred:
        cred_id = cred.id
        creds.update(cred_id, vault_id=vault_id, token=token)
    else:
        cred_id = creds.create(vault_id=vault_id, name="static_bearer", token=token).id

    # Cache for later session creation

    vault_cache[mcp_server_url] = {"cred_id": cred_id}

This implementation supports static-bearer credential management, allowing agents to authenticate with external APIs while maintaining the security boundary that prevents token exposure in logs or error messages.

Key Files and Their Security Roles

Understanding the repository structure helps developers implement vault integration correctly:

• production-ready-agent/starter/lib/anthropic.ts – SDK wrapper that reads VAULT_ID from the runtime environment
• production-ready-agent/starter/app/api/sessions/route.ts – API endpoint responsible for attaching vault_ids to session creation requests
• production-ready-agent/starter/components/NewEvaluationModal.tsx – React component enabling user selection of vault credentials for specific evaluations
• agent-battle/my_agent.py – Reference implementation showing programmatic vault and credential management in Python

Summary

Vault integration in the anthropics/cwc-workshops repository provides enterprise-grade credential security for Claude agents:

• Runtime Injection – Credentials are injected via vault_ids only during active sessions, never stored in code
• Conditional Attachment – The session API uses conditional spread syntax to include vaults only when required
• Multi-Language Support – TypeScript/React implementations for web UIs pair with Python SDK methods for backend automation
• Credential Lifecycle – Functions like _ensure_vault_credential() manage vault discovery, creation, and token rotation programmatically

Frequently Asked Questions

How does the Claude-Managed-Platform inject vault credentials into running agents?

The CMA monitors the vault_ids array included in the session creation payload. When present, the platform retrieves the corresponding credentials from the secure vault store and injects them into the agent's runtime environment as environment variables, accessible through the SDK's env() helper. This injection occurs at session startup and persists only for the duration of that specific session.

Can agents access vault credentials without using the Next.js frontend?

Yes. The agent-battle/my_agent.py implementation demonstrates direct Python SDK usage where the _session_vault_ids() function returns vault identifiers programmatically. Developers can construct session requests manually using the CMA API client, binding vaults to sessions without UI interaction, which is essential for automated testing and CI/CD pipelines.

What types of credentials can be stored in CMA vaults?

According to the implementation in agent-battle/my_agent.py, the system supports static-bearer tokens through the creds.create() and creds.update() methods. The architecture supports multiple credential formats within a single vault, allowing agents to store API keys, authentication tokens, and other sensitive strings needed for external service integration.

Is vault integration required for all Claude agents in the cwc-workshops repository?

No. The session creation logic in app/api/sessions/route.ts uses conditional inclusion (mcp && ids.vault ? { vault_ids: [ids.vault] } : {}), meaning vault attachment is optional. Agents that do not interact with external authenticated APIs can operate without vault configuration, while those requiring secure credential access can opt-in by supplying the appropriate vault identifier.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}