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

# 1Password

> Bind vault credentials to 1Password items and resolve secrets live at run time

## **How the 1Password Integration Works**

Connect a 1Password account to CloudCruise and bind your [vault](/concepts/vault) credentials to specific 1Password items. At run time, CloudCruise resolves the username, password, and one-time code directly from 1Password — **the secret values themselves are never stored in CloudCruise**.

This is useful when 1Password is already your source of truth for credentials: you rotate or update a login in 1Password, and your workflows automatically use the new value on the next run with no change in CloudCruise.

<Note>
  CloudCruise connects to 1Password using a **service account** — a non-interactive
  credential scoped to the vaults you choose. Your personal 1Password login and
  master password are never involved.
</Note>

***

### **Step 1: Create a 1Password Service Account**

1. Sign in to [1password.com](https://start.1password.com/signin?l=en) and open **Developer → Directory** (use the web app, not the desktop app).
2. Under **Access Tokens**, click **Service Account**.
3. Give it a name (e.g. "CloudCruise") and click **Next**.
4. On **Vault access**, choose the vault(s) you want to automate, open the permissions menu, and enable **Read Items** and **Write Items**. Click **Next**.
5. On **Environment access**, leave everything as **No Access** (CloudCruise doesn't use Environments) and click **Create Account**.
6. Copy the token and keep it handy for the next step.

<Warning>
  The service account token starts with `ops_` and is **shown only once**. Copy it
  before leaving the page — if you lose it, you'll need to create a new service account.
</Warning>

<Note>
  **Write Items** is optional but recommended. It's only required if you want the
  [Maintenance Agent](/concepts/maintenance-agent) to write rotated passwords back to
  1Password. Without it, connections work for read-only resolution and password
  rotations are skipped (see [Password rotation](#password-rotation-write-back)).
</Note>

### **Step 2: Connect 1Password in CloudCruise**

1. Navigate to [Workspace Settings → Integrations](https://app.cloudcruise.com/settings/integrations).
2. In the **Secret Providers** section, click **Connect 1Password**.
3. Enter:
   * **Connection name** — a label for this connection (e.g. "Acme 1Password")
   * **Service account token** — the `ops_…` token from Step 1
   * **Cache duration** — how long resolved secrets are reused before re-fetching (see [Cache duration](#cache-duration))
4. Click **Connect**. CloudCruise validates the token against 1Password before saving.

You can connect more than one 1Password account per workspace — for example, separate connections for different teams or vaults.

### **Step 3: Bind a Credential to a 1Password Item**

1. Go to your [Vault](https://app.cloudcruise.com/vault) and add or edit a credential.
2. Under **Credentials source**, choose **1Password**.
3. Select the **connection** and then the **1Password item** to bind.
4. Save the credential.

The manual username/password fields are hidden for provider-backed credentials — the values come from the bound 1Password item at run time.

<Note>
  The **Credentials source** selector only appears once you have at least one
  1Password connection set up in the workspace.
</Note>

***

## **Field Mapping**

CloudCruise reads these built-in fields from the bound 1Password login item:

| 1Password field     | Used as             |
| ------------------- | ------------------- |
| `username`          | Credential username |
| `password`          | Credential password |
| `one-time password` | TOTP / 2FA code     |

If a field is absent on the item, that value simply resolves as empty.

## **Two-Factor Authentication**

If the bound 1Password item has a **one-time password** field, CloudCruise uses it automatically for any authenticator-app (TOTP) 2FA step in your workflow — one-time codes are always resolved live and **never cached**.

For provider-backed credentials, the vault's **Two-Factor Authentication** section still lets you configure **Email**, **SMS**, and **Magic Link** methods. The **Authenticator (One-Time Password)** method is disabled, because that code is resolved from the 1Password item rather than stored in CloudCruise. See [Two-Factor Authentication](/concepts/twofactor) for how each method works.

## **Password Rotation (Write-Back)**

When the [Maintenance Agent](/concepts/maintenance-agent) rotates a credential's password, a provider-backed credential is written **back to its 1Password item** so 1Password stays the source of truth.

Before initiating a reset, CloudCruise performs a pre-flight check that the connection has **Write Items** access to the item's vault:

* **Write access present** — the new password is set on the site and written back to the 1Password item.
* **Read-only connection** — the rotation is **skipped** rather than risk changing the site password to a value that can't be saved back. Grant the service account **Write Items** for the vault (or update the password manually) to enable rotation.

## **Cache Duration**

CloudCruise can reuse a resolved username and password for a short window before fetching them from 1Password again:

| Option                  | Behavior                                     |
| ----------------------- | -------------------------------------------- |
| **Off (always live)**   | Resolve usernames and passwords on every run |
| **5 minutes** (default) | Reuse for up to 5 minutes                    |
| **1 hour**              | Reuse for up to 1 hour                       |
| **24 hours**            | Reuse for up to 24 hours                     |

Shorter durations pick up rotated secrets faster; longer durations make fewer 1Password API calls. 1Password rate-limits service accounts (≈50,000 requests/day org-wide on the Business plan), so longer caching helps high-volume workspaces stay under the limit. **One-time codes are always resolved live and never cached.**

You can set a cache duration on the connection and optionally override it per credential. To force a refresh immediately after rotating secrets in 1Password, use **Clear cached secrets** on the connection in the Integrations page.

***

## **Automating over the API, CLI, and SDKs**

Provider-backed vault entries can be created and updated through the [Vault API](/vault-api/create-vault-entry) — pass `secret_provider_id` and `secret_ref` instead of `user_name`/`password`. The connection itself is still set up once from the dashboard; the API is for binding credentials to it at scale.

**Step 1 — Find your connection ID.** [List the workspace's secret-provider connections](/vault-api/list-secret-providers):

```bash theme={null}
curl https://api.cloudcruise.com/secret-providers \
  -H "cc-key: $CC_API_KEY"
```

```json theme={null}
[
  {
    "id": "25290e80-bbd5-41b3-861e-dea30cc26e27",
    "provider_type": "1password",
    "name": "Acme 1Password",
    "cache_ttl_seconds": 300
  }
]
```

**Step 2 — Find the item reference.** [List items the connection can see](/vault-api/list-secret-provider-items); each has a `ref` in `op://<vaultId>/<itemId>` form:

```bash theme={null}
curl https://api.cloudcruise.com/secret-providers/25290e80-bbd5-41b3-861e-dea30cc26e27/items \
  -H "cc-key: $CC_API_KEY"
```

```json theme={null}
[
  {
    "id": "p3jnretb3tmnxiv74ybdxqt6zy",
    "title": "Acme Prod Login",
    "vaultName": "Automation",
    "ref": "op://w7msqbbaick7emrq2a7gnptram/p3jnretb3tmnxiv74ybdxqt6zy"
  }
]
```

**Step 3 — Create or update the vault entry.** Pass the connection id and item ref; omit `user_name`/`password` (they're resolved live):

```bash theme={null}
curl -X POST https://api.cloudcruise.com/vault \
  -H "cc-key: $CC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissioned_user_id": "acme-prod",
    "domain": "https://acme.com",
    "secret_provider_id": "25290e80-bbd5-41b3-861e-dea30cc26e27",
    "secret_ref": "op://w7msqbbaick7emrq2a7gnptram/p3jnretb3tmnxiv74ybdxqt6zy",
    "secret_cache_ttl_seconds": 300
  }'
```

`secret_cache_ttl_seconds` is optional — omit it to use the connection's default. Use `PUT /vault` with the same fields to update an existing entry; identify it with `domain` and `permissioned_user_id` (or include `id` when using the raw API). The connection must belong to the same workspace as the entry, or the request is rejected.

### **Using the CLI and SDKs**

The same flow is available through the [CLI](/sdk/cli/overview#secret-providers-1password) and the [Python](/sdk/python/vault#provider-backed-credentials-1password) and [JavaScript](/sdk/js/vault#provider-backed-credentials-1password) SDKs: list connections, list items, then bind a vault entry with the connection id and item ref.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    cloudcruise secret-providers list
    cloudcruise secret-providers items <provider_id>

    cloudcruise vault create \
      --user-id acme-prod \
      --domain "https://acme.com" \
      --secret-provider-id <provider_id> \
      --secret-ref "op://vaultId/itemId"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    providers = client.secret_providers.list()
    items = client.secret_providers.list_items(providers[0].id)

    client.vault.create(
        VaultEntryInput(
            domain="https://acme.com",
            permissioned_user_id="acme-prod",
            secret_provider_id=providers[0].id,
            secret_ref=items[0].ref,
        )
    )
    ```
  </Tab>

  <Tab title="JavaScript">
    ```typescript theme={null}
    const providers = await client.secretProviders.list();
    const items = await client.secretProviders.listItems(providers[0].id);

    await client.vault.create("https://acme.com", "acme-prod", {
      secret_provider_id: providers[0].id,
      secret_ref: items[0].ref,
    });
    ```
  </Tab>
</Tabs>

***

## **Security**

* **No secret values are stored in CloudCruise.** Usernames, passwords, and one-time codes are resolved from 1Password at run time.
* The **service account token** is encrypted at rest under your workspace key (AES-256-GCM), exactly like vault passwords. Only the last four characters are ever shown back to you.
* Resolved secrets are held only transiently and, when cached, are stored as ciphertext under your workspace key for the configured cache duration.
* The service account is scoped to the vaults you select and to **Read Items** (plus **Write Items** if you enable rotation) — nothing more.

See the [Vault security overview](/concepts/vault#security-overview) for the full encryption model.

## **Limitations**

* A vault credential can be backed by **1Password** or use a **CloudCruise passkey**, but not both — the two are mutually exclusive.
* 1Password **Environments** are not used and should be left at **No Access** when creating the service account.

***

## **Troubleshooting**

### **Connection fails to validate**

1. Confirm the token starts with `ops_` and was copied in full.
2. Make sure the service account has access to at least one vault with **Read Items**.
3. Tokens are shown only once — if in doubt, create a new service account and reconnect.

### **A bound item shows no username or password**

Check that the 1Password item is a login item with the standard `username` and `password` fields populated. Custom-named fields are not read.

### **Password rotation is being skipped**

The connection is read-only for that item's vault. Grant the service account **Write Items** on the vault in 1Password, then retry. See [Password Rotation](#password-rotation-write-back).

### **Changes in 1Password aren't reflected**

Resolved secrets may be cached. Lower the cache duration, or use **Clear cached secrets** on the connection in the [Integrations](https://app.cloudcruise.com/settings/integrations) page to force an immediate refresh.

### **Need to disconnect?**

You can disconnect a 1Password connection from the [Integrations](https://app.cloudcruise.com/settings/integrations) page. A connection that still has credentials bound to it can't be deleted — CloudCruise lists the dependent credentials so you can unbind or delete them first.