> ## 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.

# SDK Configuration

> Explore every option supported by createVaultkitClient and how to tailor the connection to your needs.

# SDK Configuration

`createVaultkitClient` accepts a `VaultkitConfig` object. Use it to control authentication, timeouts, retries, logging, and the way dynamic vaults are generated.

## Required properties

Always provide these three values when creating a client:

| Property                          | Type     | Description                                                                     |
| --------------------------------- | -------- | ------------------------------------------------------------------------------- |
| `apiKey`                          | `string` | Your Vaultkit API key (represents your organization).                           |
| `userId`                          | `string` | Identifier for the end user the agent is acting on behalf of.                   |
| `vaultId` *or* `featureMappingId` | `string` | Either a static vault ID, or a dynamic vault template ID. Only one is required. |

> **About static vs. dynamic vaults:**
>
> * Use `vaultId` if you have a pre-configured vault in the Vaultkit dashboard.
> * Use `featureMappingId` to generate vaults on demand. Vaultkit will create a per-user vault the first time `connect()` is called.

## Optional properties

Fine-tune behavior with these optional settings:

| Property            | Type                              | Default                    | Purpose                                                                                                               |
| ------------------- | --------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `selectedProviders` | `string[]`                        | `undefined`                | Restrict which providers to activate for dynamic vaults. Must be a subset of the feature mapping's providers.         |
| `selectedScopes`    | `string[]`                        | `undefined`                | Further limit provider permissions for dynamic vaults.                                                                |
| `timeout`           | `number`                          | `30000`                    | Timeout (ms) for discovery requests made during `connect()`.                                                          |
| `retries`           | `number`                          | `3`                        | Retry attempts for transient network failures.                                                                        |
| `baseUrl`           | `string`                          | `https://app.vaultkit.dev` | Only set this if using a self-hosted or custom Vaultkit instance. Default points to production.                       |
| `log`               | `(level, message, data?) => void` | Lightweight console logger | Receive verbose status messages (`info`, `warn`, `error`). Useful for piping diagnostics to your observability stack. |

## Example: Interactive flow (recommended)

This is the typical flow for apps with user-facing UIs. Users select features and authenticate providers through the SDK UI components, then you create a client with the resulting vault.

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

// After user has selected a feature via FeatureSelect UI
// and authenticated providers via AuthComponent
const vaultkit = createVaultkitClient({
  apiKey: process.env.VAULTKIT_API_KEY!,
  userId: currentUser.id,
  vaultId: userSelectedVault.id, // from FeatureSelect UI state
});

await vaultkit.connect();
```

## Example: Programmatic flow (advanced)

Use this only when you need to dynamically provision vaults server-side without user interaction.

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

// Backend agent or automation service that provisions vaults on demand
const vaultkit = createVaultkitClient({
  apiKey: process.env.VAULTKIT_API_KEY!,
  userId: targetUser.id,
  featureMappingId: "feat_customer_support", // pre-configured feature template
  selectedProviders: ["gmail", "slack"], // optional: restrict providers
  selectedScopes: ["read", "write"], // optional: restrict permissions
  timeout: 45_000, // optional: increase for slower networks
  retries: 5, // optional: more retries for unreliable connections
  log: (level, message, meta) => {
    console[level]("[vaultkit]", message, meta ?? "");
  },
});

await vaultkit.connect();
```

## Example: Backend/Internal agent (no UI)

For internal services and scheduled jobs, use pre-configured vaults without any UI components:

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

// Scheduled job or internal service
// No user interaction, just programmatic access
const vaultkit = createVaultkitClient({
  apiKey: process.env.VAULTKIT_API_KEY!,
  userId: "user_to_act_on_behalf_of",
  vaultId: "vault_daily_digest", // pre-configured in dashboard
  retries: 5, // higher retries for batch jobs
  timeout: 60_000, // longer timeout
});

await vaultkit.connect();
// vaultkit.tools is now ready to use
```

For more details on backend integration patterns, see [Backend Integration](sdk-backend-integration).

## Inspecting the client

`createVaultkitClient` returns a small API:

* `vaultkit.tools` – Getter that exposes the array of Vaultkit tools after `connect()` succeeds.
* `await vaultkit.connect()` – Resolves the correct vault and fetches tools. It also handles dynamic provisioning when `featureMappingId` is present.
* `await vaultkit.disconnect()` – Clears in-memory tool state. Call this in `finally` blocks to avoid leaking resources.

If you need to share discovery results across multiple requests (for example in a long-lived worker), keep the client in a module-level cache and call `connect()` once during startup.