Vault | BCTRL | Documentation

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.

1 const cred = await bctrl.vault.get("prod/crm/salesforce");
2 if (cred) {
3   console.log(cred.username);
4 }

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.

1 await bctrl.vault.set("prod/crm/salesforce", {
2   username: "[email protected]",
3   password: "s3cret",
4   totp: "JBSWY3DPEHPK3PXP",
5   origins: ["https://login.salesforce.com"],
6   label: "Salesforce Bot",
7 });

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.

1 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.

1 // All keys
2 const keys = await bctrl.vault.list();
3 
4 // Keys under a prefix
5 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.

1 const entries = await bctrl.vault.list({
2   meta: true,
3   prefix: "prod/",
4   hasTotp: true,
5   limit: 50,
6 });

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.

1 const code = await bctrl.vault.totp("prod/crm/salesforce");
2 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.

1 const workspace = await bctrl.workspaces.create({
2   name: "crm-agent",
3   mounts: {
4     vault: {
5       allow: ["prod/crm/"],
6       deny: ["prod/admin/"],
7       allowRawReads: true,
8     },
9   },
10 });