***

title: Vault
description: >-
Store and manage secrets — login credentials, API keys, and TOTP seeds — that
runtimes use to authenticate.
-----------------------------

The vault stores secrets that your runtimes use to authenticate into websites and services. Each entry holds a username, password, optional TOTP seed, and origin matching rules.

Access via `bctrl.vault`.

## get(key)

Retrieve a credential from the vault.

```ts
const cred = await bctrl.vault.get("prod/crm/salesforce");
if (cred) {
  console.log(cred.username);
}
```

| Parameter | Type     | Required | Description    |
| --------- | -------- | -------- | -------------- |
| `key`     | `string` | Yes      | Vault key path |

**Returns** `VaultCredential | null` — null if not found.

The returned credential contains:

| Field            | Type        | Description                                                 |
| ---------------- | ----------- | ----------------------------------------------------------- |
| `username`       | `string`    | Login username                                              |
| `password`       | `string`    | Login password                                              |
| `totp`           | `string?`   | TOTP secret seed (if configured)                            |
| `label`          | `string?`   | Human-readable label                                        |
| `origins`        | `string[]?` | Exact origin matches (e.g., `https://login.salesforce.com`) |
| `originPatterns` | `string[]?` | Glob patterns for origin matching                           |
| `notes`          | `string?`   | Free-text notes                                             |

***

## set(key, credential)

Store or update a credential.

```ts
await bctrl.vault.set("prod/crm/salesforce", {
  username: "bot@company.com",
  password: "s3cret",
  totp: "JBSWY3DPEHPK3PXP",
  origins: ["https://login.salesforce.com"],
  label: "Salesforce Bot",
});
```

| Parameter                   | Type       | Required | Description                            |
| --------------------------- | ---------- | -------- | -------------------------------------- |
| `key`                       | `string`   | Yes      | Vault key path                         |
| `credential.username`       | `string`   | Yes      | Login username                         |
| `credential.password`       | `string`   | Yes      | Login password                         |
| `credential.totp`           | `string`   | No       | TOTP secret seed for 2FA               |
| `credential.origins`        | `string[]` | No       | Exact origin matches                   |
| `credential.originPatterns` | `string[]` | No       | Glob patterns for origins              |
| `credential.matchOrigins`   | `string[]` | No       | Auto-split into origins/originPatterns |
| `credential.label`          | `string`   | No       | Human-readable label                   |
| `credential.notes`          | `string`   | No       | Free-text notes                        |

***

## delete(key)

Delete a credential from the vault.

```ts
await bctrl.vault.delete("prod/crm/salesforce");
```

| Parameter | Type     | Required | Description    |
| --------- | -------- | -------- | -------------- |
| `key`     | `string` | Yes      | Vault key path |

***

## list(prefix?)

List vault keys, optionally filtered by prefix.

```ts
// All keys
const keys = await bctrl.vault.list();

// Keys under a prefix
const prodKeys = await bctrl.vault.list("prod/crm/");
```

| Parameter | Type     | Required | Description             |
| --------- | -------- | -------- | ----------------------- |
| `prefix`  | `string` | No       | Key prefix to filter by |

**Returns** `string[]` — array of matching key paths.

***

## list(options) — with metadata

List credentials with full metadata by passing `meta: true`.

```ts
const entries = await bctrl.vault.list({
  meta: true,
  prefix: "prod/",
  hasTotp: true,
  limit: 50,
});
```

| Parameter | Type      | Required | Description               |
| --------- | --------- | -------- | ------------------------- |
| `meta`    | `true`    | Yes      | Return full metadata      |
| `prefix`  | `string`  | No       | Key prefix filter         |
| `origin`  | `string`  | No       | Filter by matching origin |
| `hasTotp` | `boolean` | No       | Filter by TOTP presence   |
| `limit`   | `number`  | No       | Max results               |

**Returns** `VaultCredentialMeta[]`

***

## totp(key)

Generate a current TOTP code from a stored credential's TOTP seed.

```ts
const code = await bctrl.vault.totp("prod/crm/salesforce");
console.log(code); // e.g., "482910"
```

| Parameter | Type     | Required | Description                |
| --------- | -------- | -------- | -------------------------- |
| `key`     | `string` | Yes      | Vault key with a TOTP seed |

**Returns** `string` — the current 6-digit TOTP code.

***

## Usage with workspaces

Vault access is scoped by key prefix when mounted to a workspace. See [Scopes & Inheritance](/sdk/concepts/scopes-and-inheritance).

```ts
const workspace = await bctrl.workspaces.create({
  name: "crm-agent",
  mounts: {
    vault: {
      allow: ["prod/crm/"],
      deny: ["prod/admin/"],
      allowRawReads: true,
    },
  },
});
```