Skip to main content

​
How the 1Password Integration Works

Connect a 1Password account to CloudCruise and bind your 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.
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.

​
Step 1: Create a 1Password Service Account

  1. Sign in to 1password.com 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.
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.
Write Items is optional but recommended. It’s only required if you want the 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).

​
Step 2: Connect 1Password in CloudCruise

  1. Navigate to Workspace 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)
  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 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.
The Credentials source selector only appears once you have at least one 1Password connection set up in the workspace.

​
Field Mapping

CloudCruise reads these built-in fields from the bound 1Password login item:
1Password fieldUsed as
usernameCredential username
passwordCredential password
one-time passwordTOTP / 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 for how each method works.

​
Password Rotation (Write-Back)

When the 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:
OptionBehavior
Off (always live)Resolve usernames and passwords on every run
5 minutes (default)Reuse for up to 5 minutes
1 hourReuse for up to 1 hour
24 hoursReuse 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

Provider-backed vault entries can be created and updated through the Vault API — 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: 
curl https://api.cloudcruise.com/secret-providers \
  -H "cc-key: $CC_API_KEY"

[
  {
    "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; each has a ref in op://<vaultId>/<itemId> form: 
curl https://api.cloudcruise.com/secret-providers/25290e80-bbd5-41b3-861e-dea30cc26e27/items \
  -H "cc-key: $CC_API_KEY"

[
  {
    "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): 
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 (plus the entry id) to update an existing entry. The connection must belong to the same workspace as the entry, or the request is rejected.

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

​
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 page to force an immediate refresh.

​
Need to disconnect?

You can disconnect a 1Password connection from the 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.