> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaultkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Vault Provisioning

> Generate per-user vaults on demand using feature mappings and the Vaultkit SDK.

# Dynamic Vault Provisioning

Dynamic vaults let you expose a single feature to customers while Vaultkit quietly provisions a dedicated vault for each end user. This keeps credentials scoped and auditable without leaking internal IDs to your integrators.

## How it works

1. Configure a **feature mapping** in the Vaultkit dashboard ([Dashboard → Feature Mappings](https://app.vaultkit.dev/dashboard/features)) in either static or dynamic mode. Set the feature name, description, providers (for example Gmail, Outlook), and the scopes each provider requires. This metadata is what `FeatureSelect` and `AuthComponent` render to end users.
2. Pass the mapping’s ID to the SDK via `featureMappingId`.
3. When `connect()` runs, the SDK checks whether a vault already exists for the end user.
   * If it exists, the SDK reuses it and loads the available tools.
   * If not, it calls `POST /api/vaultkit/generate-vault`, creates a vault with the permitted providers and scopes, and returns the new ID.
4. Tool discovery continues as normal and your agent receives the merged toolset.

## Basic implementation

```ts theme={null}
import { createVaultkitClient } from "@vaultkit/ai-sdk";

const vaultkit = createVaultkitClient({
  apiKey: process.env.VAULTKIT_API_KEY!,
  userId: customer.id,
  featureMappingId: "feat_github_triage",
});

await vaultkit.connect();
```

## Limiting providers and scopes

Dynamic mappings can allow multiple providers. If you want to capture user intent at runtime (for example GitHub **and** Slack vs. GitHub only), pass the user’s selection to the SDK.

```ts theme={null}
const vaultkit = createVaultkitClient({
  apiKey: env.VAULTKIT_API_KEY,
  userId: customer.id,
  featureMappingId: "feat_dynamic_support",
  selectedProviders: customer.selectedProviders,
  selectedScopes: customer.selectedScopes,
});
```

The SDK enforces that the requested providers/scopes are subsets of what the feature mapping allows. Anything outside that set results in an `AuthenticationError`.

## Persisting generated vaults

The SDK exposes everything it learns while provisioning:

```ts theme={null}
const vault = await vaultkit.connect();

console.log(
  "Resolved vault ID:",
  vaultkit.tools.length ? vaultkit.tools[0].vaultId : "(in tools metadata)"
);
```

If you need to surface the generated vault ID elsewhere (for example to show in your admin tools), listen to the responses from your own API layer. The Vaultkit REST API returns `generated_vault_id` in the payload from `/api/vaultkit/generate-vault`.

## Pair with the Feature Selection component

`FeatureSelection` (exported from `@vaultkit/ai-sdk`) gives end users a UI for choosing which features and providers to enable. It writes the user’s choices into the shared context so you can feed them into the client before calling `connect()`.

```tsx theme={null}
import { FeatureSelection, VaultkitProvider, useVaultkit } from "@vaultkit/ai-sdk";

function FeatureStep() {
  const { selectedFeatures, getSelectedProviders } = useVaultkit();

  // Use these helpers to populate selectedProviders / selectedScopes when connecting
  return <FeatureSelection apiKey={apiKey} userId={userId} showAllFeatures />;
}
```

Once the user confirms their selection, create a client with the chosen feature mapping ID and call `connect()` as shown above.