Vaults and Credentials

Purpose and Scope

Vaults and credentials are the Managed Agents beta resources for storing authentication material that an agent can use when it needs to reach protected systems. A vault is the container, while a credential is the specific authentication record inside that container. In the TypeScript SDK, this surface lives under client.beta.vaults, with credentials exposed as a nested resource at client.beta.vaults.credentials. That placement matters because credentials are not general client authentication settings; they are resources managed through the Claude API for Managed Agent workflows and protected integrations such as MCP servers or external services.

Sources: src/resources/beta/vaults/vaults.ts, src/resources/beta/vaults/credentials.ts

The SDK code is generated from the OpenAPI specification, so the public methods closely mirror the REST API shape. Vault operations target /v1/vaults, and credential operations target /v1/vaults/{vault_id}/credentials. Both resource classes explicitly add ?beta=true and build an anthropic-beta header that includes managed-agents-2026-04-01, while still allowing callers to pass additional beta values through the betas parameter. As a result, callers usually focus on the domain inputs, such as display names and credential authentication payloads, while the SDK handles the required Managed Agents beta header plumbing.

Sources: src/resources/beta/vaults/vaults.ts, src/resources/beta/vaults/credentials.ts

Relevant Source Files

• src/resources/beta/vaults/credentials.ts - Implements the generated Credentials resource, including create, retrieve, update, list, and exported credential-related request and response types.
• src/resources/beta/vaults/index.ts - Re-exports the vault and credential resource classes plus the concrete credential auth, networking, validation, pagination, and parameter types used by SDK consumers.
• src/lib/credentials/types.ts - Defines local SDK credential-provider primitives for OAuth and workload identity flows, including token providers, token response parsing, security checks, and beta header constants for OAuth-backed client authentication.
• src/resources/beta/vaults.ts - Re-exports the generated vaults namespace so the beta vault resources are available through the SDK module tree.
• src/resources/beta/vaults/vaults.ts - Implements the generated Vaults resource and wires credentials as a nested resource instance.
• src/resources/beta/agents/index.ts - Exports Managed Agent type names that can reference MCP toolsets, MCP server URL definitions, custom skills, and tool configuration, which are the agent-side concepts that often need vault-backed credentials.

Core Concepts

A vault should be understood as an API-managed boundary around one or more credentials. The SDK exposes Vaults.create, Vaults.retrieve, Vaults.update, and list-style behavior through the generated resource, and the example for create shows the smallest useful body: a display_name such as Example vault. Once a vault exists, credential methods take the vault identifier either as the first positional argument, for collection methods, or as vault_id in the params object, for item methods. This keeps credential identity and vault containment explicit at every call site.

Sources: src/resources/beta/vaults/vaults.ts, src/resources/beta/vaults/credentials.ts

A credential is the record that describes how a Managed Agent or an integration authenticates. The generated exports identify three creation/update families: BetaManagedAgentsMCPOAuthCreateParams, BetaManagedAgentsStaticBearerCreateParams, and BetaManagedAgentsEnvironmentVariableCreateParams. The official API documentation describes these as alternatives under the auth body parameter. In SDK usage, that means the caller chooses the authentication strategy by providing a discriminated auth object. The generated example creates a static bearer credential with a token, an mcp_server_url, and type: 'static_bearer', making the intended MCP-server use case visible in the TypeScript method documentation.

Sources: src/resources/beta/vaults/credentials.ts, src/resources/beta/vaults/index.ts

The TypeScript exports also distinguish create/update parameter types from response types. For example, the SDK exports BetaManagedAgentsMCPOAuthCreateParams separately from BetaManagedAgentsMCPOAuthAuthResponse, and similarly separates static bearer and environment variable create/update types from response types. This naming is useful when building application abstractions: code that accepts secret-bearing input should use create or update parameter types, while code that renders stored credential metadata should use response types. The official API documentation states that sensitive fields are not returned in credential responses, and the SDK type split supports that reader model.

Sources: src/resources/beta/vaults/index.ts, src/resources/beta/vaults/credentials.ts

System-to-Code Mapping

The beta vault namespace is assembled in layers. src/resources/beta/vaults.ts re-exports ./vaults/index, making the generated namespace available to the rest of the SDK. src/resources/beta/vaults/index.ts then exports both the Vaults class and the nested Credentials class, along with all related TypeScript types. Finally, src/resources/beta/vaults/vaults.ts constructs credentials: CredentialsAPI.Credentials = new CredentialsAPI.Credentials(this._client), so a single client.beta.vaults resource object can also service credential calls under client.beta.vaults.credentials. This is the same resource-composition pattern used throughout generated SDK surfaces.

Sources: src/resources/beta/vaults.ts, src/resources/beta/vaults/index.ts, src/resources/beta/vaults/vaults.ts

API Components

The compact reference below shows the primary public contracts visible in the generated SDK. The exact response type for successful credential reads and writes is BetaManagedAgentsCredential; credential deletion uses BetaManagedAgentsDeletedCredential; and list calls return PagePromise<BetaManagedAgentsCredentialsPageCursor, BetaManagedAgentsCredential>. Vault operations similarly use BetaManagedAgentsVault, BetaManagedAgentsDeletedVault, and BetaManagedAgentsVaultsPageCursor. These names are exported from src/resources/beta/vaults/index.ts, so consumers can import the types when they want to annotate helper functions, service layers, or tests around Managed Agent credential provisioning.

Sources: src/resources/beta/vaults/index.ts, src/resources/beta/vaults/vaults.ts, src/resources/beta/vaults/credentials.ts

const vault = await client.beta.vaults.create({
  display_name: 'Example vault',
});
 
const credential = await client.beta.vaults.credentials.create(vault.id, {
  auth: {
    token: 'bearer_exampletoken',
    mcp_server_url: 'https://example-server.modelcontextprotocol.io/sse',
    type: 'static_bearer',
  },
});

Credential request parameters consistently reserve betas for SDK header construction. In Credentials.create, the implementation destructures { betas, ...body }, sends only body as the JSON payload, and builds headers from the supplied beta values plus managed-agents-2026-04-01. Credentials.retrieve destructures { vault_id, betas } and uses vault_id only in the path. Credentials.update combines both patterns by extracting vault_id and betas, then sending the remaining fields as the body. This pattern prevents path and header parameters from leaking into the request body.

Sources: src/resources/beta/vaults/credentials.ts

Authentication Design and Credential Providers

Do not confuse Managed Agent vault credentials with the SDK client's own credentials. src/lib/credentials/types.ts defines local client authentication primitives such as AccessToken, AccessTokenProvider, IdentityTokenProvider, and CredentialResult. Those types power OAuth and workload-identity behavior for authenticating the SDK itself to Anthropic services. They include token endpoint constants, beta header constants, refresh thresholds, token-response parsing, and a requireSecureTokenEndpoint guard that refuses to send credentials to non-HTTPS token endpoints except loopback hosts for local development. Vault credentials, by contrast, are API resources created through client.beta.vaults.credentials.

Sources: src/lib/credentials/types.ts, src/resources/beta/vaults/credentials.ts

This split is important for secure application architecture. A server process may use an API key, OAuth access token, or workload-identity exchange to authenticate the SDK client, and then call the vault APIs to create a credential that a Managed Agent can later use. The first credential proves the application is allowed to call Anthropic; the second credential represents access to a protected integration. Keeping those concepts separate avoids accidentally embedding third-party tokens in SDK configuration, and it makes credential lifecycle operations, such as listing, updating, archiving, or deleting stored credentials, part of the Managed Agents API instead of process startup code.

Sources: src/lib/credentials/types.ts, src/resources/beta/vaults/index.ts

Agent Integration Flow

A typical Managed Agent setup starts by defining the agent and its tool access, then provisioning the vault credentials required by those tools. The agent exports include MCP-related concepts such as BetaManagedAgentsMCPToolset, BetaManagedAgentsMCPToolConfig, BetaManagedAgentsMCPServerURLDefinition, and BetaManagedAgentsURLMCPServerParams. Those types show where credentials become operationally relevant: an agent using an MCP server or a protected custom integration needs a way to authenticate when it invokes that tool. Vault credentials provide the API-managed place to store those auth details rather than placing them directly in agent instructions or local environment variables.

Sources: src/resources/beta/agents/index.ts, src/resources/beta/vaults/credentials.ts

For implementation, create the vault first, create one or more credentials inside it, and then configure the surrounding Managed Agent resources to reference the appropriate protected integration according to the API objects you are using. When listing credentials, prefer the SDK's async iteration pattern shown in the generated example: for await (const credential of client.beta.vaults.credentials.list(vaultID)). This allows application code to handle cursor pagination without manually tracking cursors, while still preserving the generated cursor-page types for callers that need lower-level control.

Sources: src/resources/beta/vaults/credentials.ts, src/resources/beta/agents/index.ts

Next Steps

Use this page when you are designing the authentication boundary for Managed Agents. Start with client.beta.vaults.create to establish a named container, then create credentials with the auth strategy that matches your integration: MCP OAuth, static bearer, or environment variable. Keep SDK-client authentication in your application configuration and keep integration credentials in the vault resource model. For adjacent implementation details, read the Managed Agents setup page for agent creation, the MCP integration page for tool connectivity, and the beta Managed Agent resources reference for the full generated resource catalog.

Sources: src/resources/beta/vaults/vaults.ts, src/resources/beta/vaults/credentials.ts, src/resources/beta/agents/index.ts