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.

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.

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:

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.

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.

Overview

Welcome

Vaultkit SDK

SDK Configuration

SDK Configuration

Required properties

Optional properties

Example: Interactive flow (recommended)

Example: Programmatic flow (advanced)

Example: Backend/Internal agent (no UI)

Inspecting the client

​SDK Configuration

​Required properties

​Optional properties

​Example: Interactive flow (recommended)

​Example: Programmatic flow (advanced)

​Example: Backend/Internal agent (no UI)

​Inspecting the client

SDK Configuration

Required properties

Optional properties

Example: Interactive flow (recommended)

Example: Programmatic flow (advanced)

Example: Backend/Internal agent (no UI)

Inspecting the client