Skip to main content

​
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:
PropertyTypeDescription
apiKeystringYour Vaultkit API key (represents your organization).
userIdstringIdentifier for the end user the agent is acting on behalf of.
vaultId or featureMappingIdstringEither 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:
PropertyTypeDefaultPurpose
selectedProvidersstring[]undefinedRestrict which providers to activate for dynamic vaults. Must be a subset of the feature mapping’s providers.
selectedScopesstring[]undefinedFurther limit provider permissions for dynamic vaults.
timeoutnumber30000Timeout (ms) for discovery requests made during connect().
retriesnumber3Retry attempts for transient network failures.
baseUrlstringhttps://app.vaultkit.devOnly set this if using a self-hosted or custom Vaultkit instance. Default points to production.
log(level, message, data?) => voidLightweight console loggerReceive verbose status messages (info, warn, error). Useful for piping diagnostics to your observability stack.
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.