1Password Provider

The 1Password provider integrates with 1Password for team-based secret management with advanced access controls.

At a glance

Provider	onepassword
URI	onepassword://[account@]vault
Access	Read and write
Best for	Team-managed secrets in 1Password vaults
Authentication	Desktop app integration, a service account token, or a legacy shell session
Default storage	Secure Note monosecret/{project}/{profile}/{key}

Quick start

# Set a secret
$ monosecret set DATABASE_URL --provider onepassword://Production
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret 'DATABASE_URL' saved to onepassword (profile: default)

# Get a secret
$ monosecret get DATABASE_URL --provider onepassword://Production

# Run with secrets
$ monosecret run --provider onepassword://Production -- npm start

Setup

Prerequisites

• 1Password CLI (op)
• 1Password account

Choose one of the following authentication methods.

Desktop app integration (recommended for local dev)

In the 1Password desktop app, open Settings → Developer and enable “Integrate with 1Password CLI”. Once enabled, op calls made by monosecret are unlocked through the desktop app via biometrics (Touch ID / Windows Hello / system password) — no shell session needed and nothing expires from under you.

Under desktop integration, op whoami reports account is not signed in even when secret access works, so monosecret probes auth via op vault list instead. It also strips any OP_SESSION_* environment variables from spawned op processes, so a stale eval $(op signin) session in your shell can’t shadow the desktop integration.

Linux note

On Linux, the desktop integration requires the op binary to be in the onepassword-cli group with the setgid bit set — the desktop app verifies the caller’s GID over its unlock socket. On NixOS this is handled automatically by programs._1password.enable = true. A plain pkgs._1password-cli install (e.g. via nix-env or Home Manager only) does not carry the setgid bit and desktop integration will fail; use the NixOS module, or fall back to a service account token for headless setups.

Service account token

In Monosecret 0.2 and later, you can declare the token as a provider credential, for example to load it from your keyring:

monosecret.toml

[providers]
op = { uri = "onepassword://Production", credentials = { service_account_token = "keyring" } }

When no explicit service_account_token is supplied, the provider falls back to OP_SERVICE_ACCOUNT_TOKEN. The onepassword+token:// scheme selects service account authentication and takes the token from one of those two sources.

Caution

From Monosecret 0.2 on, the token may not be written into the URI itself (onepassword+token://token@vault and onepassword+token://account:token@vault are rejected). A URI reaches committed manifests, shell history, and CI logs, so the token belongs in a provider credential or the environment. Keep the scheme and drop the token: onepassword+token://Production.

Manual signin (legacy)

Run eval $(op signin) to set per-shell OP_SESSION_* tokens. These expire after 30 minutes of inactivity; if they expire mid-session, monosecret falls back to desktop integration when available.

Provider credentials

Credential	Environment fallback	Available since
service_account_token	OP_SERVICE_ACCOUNT_TOKEN	0.2+

See the complete provider credential reference for all supported providers and environment fallbacks.

Configuration

URI format

onepassword://[account@]vault
onepassword+token://vault

• account: Optional account shorthand
• vault: Target vault name (defaults to “Private”)

The onepassword+token:// form selects service account authentication; supply the token as the service_account_token provider credential or through OP_SERVICE_ACCOUNT_TOKEN.

The URI names a vault only; item paths (e.g. onepassword://Vault/item/field) are rejected. To name a specific item, see Use existing secrets.

URI examples

onepassword://Production
onepassword://work@DevVault
onepassword+token://Production
onepassword://

Project configuration

monosecret.toml

[providers]
team = "onepassword://Production"

[profiles.production]
DATABASE_URL = { description = "Database URL", providers = ["team"] }

Storage model

Monosecret creates Secure Notes named monosecret/{project}/{profile}/{key} in the selected vault. The secret value is stored in the note’s value field.

Use existing secrets

If your secrets already live in 1Password items you manage yourself, name those items with the ref field and route the secret at a vault with providers:

monosecret.toml

[profiles.production]
DATABASE_URL = { description = "Production DB", ref = { item = "Postgres", field = "connection-url" }, providers = ["onepassword://Infra"] }
STRIPE_API_KEY = { description = "Stripe key", ref = { item = "Stripe", field = "api key" }, providers = ["onepassword://Infra"] }

The coordinates translate to 1Password as follows:

• item: the item title or UUID. Spaces are fine.
• field: the field label. Without field, the item is read like a convention secret (its value or password field), and writes edit the value field.
• vault: overrides the URI’s default vault for this one secret, e.g. ref = { vault = "Production", item = "infra", field = "token" }.
• section: addresses a field inside a section; requires field.

Writes go through op item edit: monosecret set updates the referenced field in place, adding the field to the item if it is missing. Items are never created through a ref.

A ref does not pin the store. Provider resolution works as usual, so a providers chain can fall back to other stores, and --provider dotenv:.env.fixtures redirects these secrets to a fixtures file during tests.

Native reference strings from the 1Password app’s Copy Secret Reference (op://vault/item/field) are not accepted directly; pasting one into ref produces an error that spells out the translation:

# op://Infra/Postgres/connection-url becomes:
DATABASE_URL = { description = "Production DB", ref = { vault = "Infra", item = "Postgres", field = "connection-url" }, providers = ["onepassword://Infra"] }

Service account rate limits

1Password bills service accounts per request, and every secret reference resolved by op inject is an individually billed read. Monosecret therefore avoids op inject on the happy path and batches item reads instead:

• One auth probe per run (op vault list), deduplicated across every provider instance.
• All referenced items in a vault are served by one batched op item get — one billed read per item, however many secrets read fields of it. A whole profile pinned to a single shared item (the op+token://Vault/Item layout) costs that one read, not one per secret.
• Convention secrets are served by one op item list plus one batched op item get per vault.
• op inject (and per-secret reads) remain only as a correctness fallback for references the item reads cannot serve, such as ambiguous item titles.

When 1Password answers with Too many requests, Monosecret surfaces the error immediately instead of retrying: while throttled, every retried attempt is itself a billed request that extends the lockout. Inspect your current usage with op service-account ratelimit.

Advanced configuration

Profile configuration

monosecret.toml

[providers]
development = "onepassword://Development"
production = "onepassword://Production"

[profiles.development.defaults]
providers = ["development"]

[profiles.production.defaults]
providers = ["production"]

CI/CD

# Set token
$ export OP_SERVICE_ACCOUNT_TOKEN="ops_eyJ..."

# Run command
$ monosecret run --provider onepassword://Production -- deploy