UNDERSTANDING 1PASSWORD AS A SWAMP VAULT

1Password is a natural home for secrets a team already manages by hand: API keys, database passwords, deploy tokens. The @swamp/1password extension lets Swamp use those same items without copying them anywhere else. This page covers how that connection is put together and the choices it leaves to you.

A vault provider, not a behavior type

In Swamp, 1Password is a vault provider. It adds no behavior type and no methods of its own. It sits beside the other primitives and answers one question: given a vault name and a key, what is the secret? Behaviors, workflows and data refer to secrets through vault.get() expressions. The value is resolved at run time and is never written into a definition or stored as data. This means 1Password can replace the default encrypted vault, or sit alongside it, without any change to how definitions are written. Only the vault name in the expression changes. The Vaults reference describes that common contract.

Why everything goes through op

The extension does not talk to the 1Password API directly. Every read, write, list, delete and annotation runs the op CLI as a child process. This keeps authentication in one place: whatever way op is signed in, Swamp uses it, and 1Password's own handling of sessions, biometrics and service accounts carries over unchanged.

The cost is a runtime dependency. op has to be installed and on PATH on every machine that resolves a secret. That includes CI runners and, under remote execution, worker machines, not only the laptop where the vault was created. Vault commands also need a signed-in Swamp account, so a machine needs both kinds of sign-in, Swamp and op, before it can resolve a secret.

Mapping keys onto items and fields

A 1Password item has many fields, while a Swamp vault key names one value. The extension bridges the two with three key formats. A bare item name reads the password field. item-name/field reads a named field. An op:// URI goes to op unchanged.

The bare form suits the common case of one secret per item, and it keeps expressions short. The field form suits items that already group related values, such as a database login with a username, password and host. The URI form is an escape hatch. It can reach items outside the vault set in op_vault, which is useful but makes the vault's boundary less clear. Teams generally do better by choosing one convention and sticking to it, because a definition that mixes all three is harder to read and review than one that uses a single form throughout.

One Swamp vault per 1Password vault

Each Swamp vault is bound to one 1Password vault through the required op_vault setting, and optionally to one account through op_account. Splitting along these lines is deliberate. A Swamp vault name then tells you exactly which 1Password vault and account a secret comes from. Access can also be granted or withheld per Swamp vault. Teams often create one Swamp vault per environment, such as staging and production, or one per account, so that a run that only needs staging credentials cannot resolve production ones. Limit Which Vaults a Run Can Use shows how a server enforces that.

Choosing an authentication mode

op supports several ways to sign in, and the right one depends on where Swamp runs.

Desktop app integration fits interactive work on a developer's machine. It uses the person's own 1Password session and needs no long-lived token, but it does need someone present to approve access. It does not suit unattended runs.

A service account suits CI and servers. The token can live in OP_SERVICE_ACCOUNT_TOKEN, which is the usual approach but exposes the token to every process in that environment. The op_service_account_token_file setting is the narrower alternative: Swamp reads the token from a file and hands it only to the op child process. Where other tools share the environment, this is the safer default. Authenticate a 1Password vault with a token file walks through it.

A Connect Server, configured through OP_CONNECT_HOST and OP_CONNECT_TOKEN, suits organisations that already run one to cache vault contents inside their network. For general setup of each mode, see Use 1Password.

Metadata, deletion and observability

Secrets pile up, and a year later it is hard to remember why a token exists or where it was issued. The extension supports swamp vault annotate and swamp vault inspect, so a URL, notes and labels can travel with each secret. It also supports swamp vault delete, so cleanup does not require switching to the 1Password app.

Because every operation crosses a process boundary and usually a network, failures can be hard to place. The extension emits an OpenTelemetry span for each vault operation and a child span for each op call, so a slow or failing run can be traced to the specific call. This only takes effect once a tracer provider is configured. See Set Up OpenTelemetry. Reads can also be recorded in Swamp's own trail, described in Enable and Query the Vault Audit Trail.

Moving secrets in and out

Few teams start with 1Password as their only vault. Some begin with the local encrypted vault and move to 1Password once several people need the same secrets. Others keep cloud credentials in a cloud provider's secrets manager and keep everything else in 1Password. Migrate a Vault covers moving secrets from one vault to another, and Route Sensitive Fields to Specific Vaults covers sending particular sensitive fields to 1Password while other vaults keep the rest.