Vault & Secrets

Busabase Cloud Vault is the place to store credentials, tokens, account IDs, model settings, webhook secrets, and other runtime configuration that Busabase-hosted code should read from context instead of hardcoding.

Secrets and variables

Use Secrets for sensitive values such as API keys, signing secrets, OAuth tokens, passwords, and private credentials. Secrets are masked in the UI unless a user with Reveal access explicitly reveals them.

Use Variables for non-sensitive runtime configuration such as provider names, model names, default regions, account aliases, or feature flags.

Names must use uppercase letters, numbers, and underscores, for example EMAIL_API_KEY, EMAIL_PROVIDER, or MODEL_PROVIDER.

Scope model

Vault values can be configured at three Cloud scopes today:

User defaults belong to your account. They are the baseline values Busabase uses when it runs code for you.

Space overrides belong to a workspace. They override matching user defaults for work inside that Space.

API key overrides belong to one API key. They override matching user and Space values when a request authenticates with that key.

Runtime precedence is:

API key overrides > Space overrides > User defaults

For example, set EMAIL_PROVIDER=resend as a user default, set MODEL_PROVIDER=openai for one Space, then set EMAIL_API_KEY differently on two API keys to run the same email skill against separate sending accounts.

The Vault data model reserves Base, Agent, and Tool scopes for future fine-grained overrides. The current Busabase Cloud UI exposes User, Space, and API key scopes.

Configure Vault items

1. Open Account Settings.
2. Go to Vault.
3. Choose User defaults, Space overrides, or API key overrides.
4. Choose Secrets or Variables.
5. Add the name, value, optional description, and access settings.
6. Save the Vault set.

Overrides are optional. If a scope has no value for a name, Busabase falls back to the next lower scope.

Access controls

Each Vault item has four explicit capabilities:

Runtime lets Busabase-hosted execution use the value.

Reveal lets an authorized user reveal the stored secret value in the UI.

Edit lets an authorized user update or delete the item.

Share is reserved for sharing/delegation workflows.

Busabase audits Vault creation, updates, deletion, reveal actions, and runtime reads so teams can answer who created a value, who used it at runtime, and who revealed it.

Runtime behavior

Busabase Cloud resolves Vault runtime values on the server after session or API-key authentication. SDK, REST, and MCP clients do not call a public Vault endpoint and do not receive secret values directly.

import { getContextVaultRuntimeValue } from "busabase-core/context";

const emailApiKey = getContextVaultRuntimeValue("EMAIL_API_KEY");

Session-authenticated requests receive User defaults plus the active Space overrides. API-key authenticated requests receive User defaults, Space overrides, and matching API-key overrides.

The open-source apps/busabase app uses a single-player Vault. Its local user scope and local Space scope are fixed because the open-source app has no login system.

API boundary

There is no public GET /api/v1/vault secret endpoint. Vault values are managed from Account Settings and consumed only inside Busabase Cloud's server-side runtime.

Migration notes

Legacy runtime configuration storage remains only for migration compatibility until the Vault migration is confirmed complete. New documentation, UI, runtime context, and API contracts use Vault & Secrets.