> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault

> Manage encrypted credentials with the TypeScript/JavaScript SDK

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

<Note>
  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.
</Note>

## Setup

```typescript theme={null}
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](https://app.cloudcruise.com/settings/encryption-keys).

## Creating a Vault Entry

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

```typescript theme={null}
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](/integrations/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](/integrations/1password), 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()`):

```typescript theme={null}
// 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                 |

<Note>
  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.
</Note>

## Getting Vault Entries

Retrieve vault entries with optional filtering:

```typescript theme={null}
// 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,
});
```

### Filter Options

| 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`) |

<Note>
  When filtering, both `domain` and `permissioned_user_id` must be provided together.
</Note>

## Updating a Vault Entry

Update an existing vault entry:

```typescript theme={null}
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](#provider-backed-credentials-1password):

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
// 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);
```

<Tip>
  The input variable name (e.g., `USER`) depends on how your workflow is configured. Check your workflow's input schema in the CloudCruise dashboard.
</Tip>