Skip to main content

​
Core Concepts

Vaultkit’s SDK mirrors the same objects you configure in the dashboard. Understanding how they fit together helps you reason about what the UI components render and which credentials your agent receives.

​
Feature

A feature is the customer-facing bundle you expose in your product (for example “Email assistant”). Features are created in the dashboard and include:
  • A title and description your end users recognize.
  • The list of providers (integrations) required for that capability.
  • The scopes/permissions each provider needs.
  • An optional connection to a specific vault (static mode) or instructions for generating one per user (dynamic mode).
FeatureSelect surfaces these features so end users can opt into the flows they need.

​
Provider

A provider represents an external service (Gmail, Outlook, Slack, GitHub, etc.) exposed through Vaultkit. Providers are attached to features and vaults, and they determine which OAuth buttons appear in AuthComponent.

​
Vault

A vault is a per-user configuration that defines which providers and tools are available to your agent. Think of it as a permission set—it specifies what providers (Gmail, Slack, etc.) the user has connected and what tools the agent is allowed to call on their behalf. Vaults can be created two ways:
  • Static – One vault with a fixed set of providers. You create this in the dashboard and reuse the same vault ID across multiple users. Best for internal agents and backend services where all users need the same set of tools. For example, a scheduled email job might have a vault with just Gmail connected.
  • Dynamic – One vault per user, created automatically when they enable a feature. Best for user-facing apps where different users might select different providers.
Note: Features are optional. They exist to help app builders organize which providers are available to users. For internal agents, you can skip features entirely and create a vault directly with whatever providers you need. When createVaultkitClient() connects, it looks up the vault, verifies which providers are connected, and returns the list of available tools your agent can call.

​
Tool

A tool is an executable action (usually proxied through Composio) that your agent can call, such as “Send Gmail message” or “Create GitHub issue.” Tools are attached to vaults; when createVaultkitClient().connect() runs, it returns the list of tools the agent is allowed to use. These map directly onto the tool schema you pass into the Vercel AI SDK or another LLM runtime.

​
Approval (coming soon)

An approval is a human-in-the-loop gate on a tool. This capability is on our roadmap; when released, the dashboard will let you flag sensitive tools, the SDK will raise an ApprovalError until an operator decides, and telemetry will record each decision. For now, treat approvals as a planned enhancement.

​
How they relate

Feature (Email assistant)
 ├── Providers: Gmail, Outlook
 ├── Scopes: read, send, delete
 └── Vault(s)
      ├── Static vault (shared) or dynamic per end user
      └── Tools (Send email, Draft reply, Archive thread)
  1. You define the feature and its providers in the dashboard.
  2. End users enable the feature via FeatureSelect and authenticate each provider through AuthComponent.
  3. The SDK resolves the vault tied to that feature/user and exposes the tool list to your agent.
  4. Approvals and telemetry keep humans in control of sensitive actions.
Keep this mental model handy while building—every SDK call maps back to these primitives.