Vault Client

The Vault client provides secure credential management with AES-256-GCM encryption. Store usernames, passwords, and other sensitive data for use in workflow executions.

All sensitive fields (user_name, password, and tfa_secret) are automatically encrypted by the SDK before being sent to CloudCruise servers. Plaintext credentials are never transmitted or stored.

Setup

import { CloudCruise } from 'cloudcruise';

const client = new CloudCruise({
  apiKey: "your-api-key",
  encryptionKey: "your-encryption-key",
});

The encryptionKey is required for vault operations. Get it from CloudCruise Settings.

Creating a Vault Entry

Use client.vault.create() to store new credentials:

const entry = await client.vault.create(
  "https://example.com",           // domain
  "unique-user-id",                // permissioned_user_id
  {
    user_name: "john@example.com",
    password: "secret-password",
    user_alias: "John's Account",
  }
);

console.log("Created vault entry:", entry.id);

Parameters

Parameter	Type	Required	Description
`domain`	`string`	Yes	Target domain for the credentials (e.g., `https://example.com`)
`permissioned_user_id`	`string`	Yes	Unique identifier to reference this entry in workflows
`options`	`object`	No	Additional fields (see below)

Options Object

Field	Type	Description
`user_name`	`string`	Username or email for authentication
`password`	`string`	Password credential
`secret_provider_id`	`string`	Bind to a 1Password connection instead of `user_name`/`password`. Must be set together with `secret_ref`
`secret_ref`	`string`	Secret-provider item reference (e.g. `op://vaultId/itemId`) resolved live at run time
`secret_cache_ttl_seconds`	`number`	Override the connection’s cache TTL for this credential, in seconds
`user_alias`	`string`	Human-readable label for the entry
`tfa_secret`	`string`	TOTP secret for two-factor authentication
`tfa_method`	`string`	TFA method: `"AUTHENTICATOR"`, `"EMAIL"`, `"MAGIC_LINK"`, or `"SMS"`
`persist_cookies`	`boolean`	Maintain cookies across workflow executions
`persist_local_storage`	`boolean`	Maintain local storage across executions
`persist_session_storage`	`boolean`	Maintain session storage across executions
`skip_csrf_cookies`	`boolean`	Skip injecting CSRF-related cookies (e.g. XSRF-TOKEN) during session restore
`allow_multiple_sessions`	`boolean`	Allow concurrent workflow sessions with these credentials
`max_concurrency`	`number`	Maximum concurrent sessions (when `allow_multiple_sessions` is true)
`proxy`	`object`	Proxy configuration with `enable` (boolean) and `target_ip` (string)

Provider-Backed Credentials (1Password)

If your workspace has a 1Password connection, you can bind a vault entry to a 1Password item instead of storing a user_name and password. CloudCruise resolves the username, password, and one-time code from 1Password at run time — the secret values are never stored in CloudCruise. Use client.secretProviders to discover the connection and item reference, then pass secret_provider_id and secret_ref to create() (or update()):

// 1. List the workspace's secret-provider connections
const providers = await client.secretProviders.list();
const provider = providers[0];

// 2. List items the connection can see, and pick one
const items = await client.secretProviders.listItems(provider.id);
const item = items[0];

// 3. Bind a vault entry to the item — no user_name/password
const entry = await client.vault.create("https://example.com", "acme-prod", {
  secret_provider_id: provider.id,
  secret_ref: item.ref,
  secret_cache_ttl_seconds: 300, // optional; omit to use the connection default
});

SecretProvider Fields

Field	Type	Description
`id`	`string`	Connection ID — pass as `secret_provider_id`
`provider_type`	`string`	Provider type (currently `"1password"`)
`name`	`string`	Connection label set in the dashboard
`cache_ttl_seconds`	`number \| null`	The connection’s default cache TTL

SecretProviderItem Fields

Field	Type	Description
`id`	`string`	Provider-side item ID
`title`	`string`	Item title in 1Password
`ref`	`string`	Item reference (`op://vaultId/itemId`) — pass as `secret_ref`
`vaultName`	`string \| null`	Name of the 1Password vault the item lives in

Validation enforced by the SDK before the request is sent:

secret_provider_id and secret_ref must be provided together.
A provider-backed entry cannot also include user_name, password, or tfa_secret — those are resolved from the provider.
secret_cache_ttl_seconds requires secret_provider_id/secret_ref and must be a non-negative integer.

Getting Vault Entries

Retrieve vault entries with optional filtering:

// Get all entries
const allEntries = await client.vault.get();

// Get specific entry by domain and user ID
const entries = await client.vault.get({
  domain: "https://example.com",
  permissioned_user_id: "unique-user-id",
});

// Get entries without decrypting credentials
const entriesEncrypted = await client.vault.get({
  domain: "https://example.com",
  permissioned_user_id: "unique-user-id",
  decryptCredentials: false,
});

Field	Type	Description
`domain`	`string`	Filter by target domain
`permissioned_user_id`	`string`	Filter by user ID
`decryptCredentials`	`boolean`	Whether to decrypt credentials (default: `true`)

When filtering, both domain and permissioned_user_id must be provided together.

Updating a Vault Entry

Update an existing vault entry:

const updatedEntry = await client.vault.update({
  domain: "https://example.com",
  permissioned_user_id: "unique-user-id",
  user_name: "new-username@example.com",
  password: "new-password",
  user_alias: "Updated Account Name",
});

Required Fields for Update

Field	Required
`domain`	Yes
`permissioned_user_id`	Yes
`user_name`	Yes — unless the update is provider-backed
`password`	Yes — unless the update is provider-backed

A direct update still requires both user_name and password. For a provider-backed update, omit them and pass secret_provider_id and secret_ref instead — the same mutual-requirement and conflict rules apply as on create:

const updatedEntry = await client.vault.update({
  domain: "https://example.com",
  permissioned_user_id: "acme-prod",
  secret_provider_id: provider.id,
  secret_ref: item.ref,
});

Deleting a Vault Entry

Delete a vault entry by domain and user ID:

await client.vault.delete({
  domain: "https://example.com",
  permissioned_user_id: "unique-user-id",
});

Using Vault Entries in Workflows

Reference vault credentials in workflow runs by passing the permissioned_user_id as an input variable:

// First, ensure the vault entry exists
let entries = await client.vault.get({
  domain: "https://login.example.com",
  permissioned_user_id: "user-123",
});

if (!entries || entries.length === 0) {
  await client.vault.create(
    "https://login.example.com",
    "user-123",
    {
      user_name: "john@example.com",
      password: "secret-password",
    }
  );
}

// Start the workflow with the vault entry reference
const run = await client.runs.start({
  workflow_id: "your-workflow-id",
  run_input_variables: {
    USER: "user-123",  // References the permissioned_user_id
  },
});

const result = await run.wait();
console.log("Run completed:", result.status);

The input variable name (e.g., USER) depends on how your workflow is configured. Check your workflow’s input schema in the CloudCruise dashboard.

Getting Started

Concepts

API Reference

SDK

Integrations

Vault

Vault Client

Setup

Creating a Vault Entry

Parameters

Options Object

Provider-Backed Credentials (1Password)

SecretProvider Fields

SecretProviderItem Fields

Getting Vault Entries

Updating a Vault Entry

Required Fields for Update

Deleting a Vault Entry

Using Vault Entries in Workflows

​Vault Client

​Setup

​Creating a Vault Entry

​Parameters

​Options Object

​Provider-Backed Credentials (1Password)

​SecretProvider Fields

​SecretProviderItem Fields

​Getting Vault Entries

​Filter Options

​Updating a Vault Entry

​Required Fields for Update

​Deleting a Vault Entry

​Using Vault Entries in Workflows

Vault Client

Setup

Creating a Vault Entry

Parameters

Options Object

Provider-Backed Credentials (1Password)

SecretProvider Fields

SecretProviderItem Fields

Getting Vault Entries

Filter Options

Updating a Vault Entry

Required Fields for Update

Deleting a Vault Entry

Using Vault Entries in Workflows