@varlock/1password-plugin

This package is a Varlock plugin that enables loading data from 1Password into your configuration.

Features

• Service account authentication for CI/CD and production environments
• Desktop app authentication for local development (with biometric unlock support)
• Connect server authentication for self-hosted 1Password infrastructure
• Secret references using 1Password's standard op:// format
• Bulk-load environments with opLoadEnvironment() via @setValuesBulk
• Multiple vault support for different environments and access levels
• Multiple instances for connecting to different accounts or vaults
• Compatible with any 1Password account type (personal, family, teams, business)
• Comprehensive error handling with helpful tips

Installation

If you are in a JavaScript based project and have a package.json file, you can either install the plugin explicitly

npm install @varlock/1password-plugin

And then register the plugin without any version number

# @plugin(@varlock/1password-plugin)

Otherwise just set the explicit version number when you register it

# @plugin(@varlock/[email protected])

See our Plugin Guide for more details.

Setup + Auth

After registering the plugin, you must initialize it with the @initOp root decorator.

Service account setup (for deployed environments)

For deployed environments (CI/CD, production, etc), you'll need a service account token:

# @plugin(@varlock/1password-plugin)
# @initOp(token=$OP_TOKEN)
# ---

# @type=opServiceAccountToken @sensitive
OP_TOKEN=

How to create a service account:

1. Navigate to your 1Password web interface
2. Go to Service Accounts → Create a new service account
3. Grant access to necessary vault(s)
4. Copy the service account token (displayed only once!)
5. Set the token in your deployed environments using your platform's env var management

:::note Vault access rules cannot be edited after creation. If your vault setup changes, you'll need to create a new service account. :::

Desktop app auth (for local dev)

During local development, you can use the 1Password desktop app instead of a service account:

# @plugin(@varlock/1password-plugin)
# @initOp(token=$OP_TOKEN, allowAppAuth=true, account=acmeco)
# ---

# @type=opServiceAccountToken @sensitive
OP_TOKEN=

Setup requirements:

1. Install the op CLI: Installation guide
2. Enable desktop app + CLI integration in 1Password settings
3. Specify your account shorthand (optional but recommended)
   • Run op account list to see available accounts
   • The shorthand is the subdomain of your x.1password.com sign-in address

When enabled, if the service account token is empty, the plugin will use the desktop app for authentication. With biometric unlock enabled, this provides a secure and convenient development experience.

:::note Keep in mind that this method connects as YOU who likely has more access than a tightly scoped service account. Consider only enabling this for non-production secrets. :::

Connect server setup (self-hosted)

If you are running a self-hosted 1Password Connect server, you can authenticate using a Connect server URL and token:

# @plugin(@varlock/1password-plugin)
# @initOp(connectHost="http://connect-server:8080", connectToken=$OP_CONNECT_TOKEN)
# ---

# @type=opConnectToken @sensitive
OP_CONNECT_TOKEN=

Setup requirements:

1. Deploy a 1Password Connect server
2. Create a Connect token with access to the required vault(s)
3. Set the OP_CONNECT_TOKEN environment variable

This method uses the Connect server REST API directly — no op CLI or 1Password SDK is required.

:::note The opLoadEnvironment() function is not supported with Connect server auth. Use op() to read individual items instead. :::

Multiple instances

If you need to connect to multiple accounts or vault configurations, register multiple named instances:

# @initOp(id=notProd, token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
# @initOp(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false)

Reading secrets

This plugin introduces the op() function to fetch secret values using 1Password secret references.

# @plugin(@varlock/1password-plugin)
# @initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
# ---

# @type=opServiceAccountToken @sensitive
OP_TOKEN=

# Fetch secrets using 1Password secret references
DB_PASS=op(op://my-vault/database-password/password)
API_KEY=op(op://api-vault/stripe/api-key)

How to find a secret reference:

In 1Password, click on the down arrow icon on any field and select Copy Secret Reference.

Multiple instances

If using multiple plugin instances:

# @initOp(id=dev, token=$OP_TOKEN_DEV, allowAppAuth=true)
# @initOp(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false)
# ---

DEV_ITEM=op(dev, op://vault-name/item-name/field-name)
PROD_ITEM=op(prod, op://vault-name/item-name/field-name)

Loading 1Password Environments

Use opLoadEnvironment() with @setValuesBulk to load all variables from a 1Password environment at once:

# @plugin(@varlock/1password-plugin)
# @initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
# @setValuesBulk(opLoadEnvironment(your-environment-id))
# ---

# @type=opServiceAccountToken @sensitive
OP_TOKEN=

API_KEY=
DB_PASSWORD=

With a named instance:

# @initOp(id=prod, token=$OP_TOKEN_PROD, allowAppAuth=false)
# @setValuesBulk(opLoadEnvironment(prod, your-environment-id))

Note: When using desktop app auth (allowAppAuth), the op environment command requires a beta version of the 1Password CLI (v2.33.0+). Download it from the CLI release history (click "show betas"). Service account auth via the SDK does not have this requirement.

Reference

Root decorators

@initOp()

Initialize a 1Password plugin instance - setting up options and authentication. Can be called multiple times to set up different instances.

Parameters:

• token?: string - Service account token. Should be a reference to a config item of type opServiceAccountToken.
• allowAppAuth?: boolean - Enable authenticating using the local desktop app (defaults to false)
• account?: string - Limits the op CLI to connect to specific 1Password account (shorthand, sign-in address, account ID, or user ID)
• connectHost?: string - URL of a self-hosted 1Password Connect server (e.g., http://connect-server:8080)
• connectToken?: string - API token for the Connect server. Should be a reference to a config item of type opConnectToken. Required when connectHost is set.
• id?: string - Instance identifier for multiple instances (defaults to _default)

Functions

op()

Fetch an individual field using a 1Password secret reference.

Signatures:

• op(secretReference) - Fetch from default instance
• op(instanceId, secretReference) - Fetch from a specific instance

Secret Reference Format:

• Format: op://vault-name/item-name/field-name
• Example: op://production/database/password

opLoadEnvironment()

Load all variables from a 1Password environment. Intended for use with @setValuesBulk.

Signatures:

• opLoadEnvironment(environmentId) - Load from default instance
• opLoadEnvironment(instanceId, environmentId) - Load from a specific instance

Data Types

• opServiceAccountToken - 1Password service account token (sensitive, validated format)
• opConnectToken - API token for a self-hosted 1Password Connect server (sensitive)

1Password Setup

Vault Organization

If your secrets live in a vault with other sensitive data, create a new vault and move your secrets to it. 1Password's access system is based on vaults, not individual items.

You can create multiple vaults to segment access to different environments, services, etc.

Best practices:

• Have a vault for highly sensitive production secrets
• Have another vault for everything else
• Grant team members access based on their needs
• Follow the principle of least privilege

Create a Service Account

1. Log in to your 1Password web interface (can only be done in web)
2. Navigate to Service Accounts → Create service account
3. Grant access to necessary vault(s) during creation
4. Copy the service account token (shown only once!)
5. Save the token securely in another vault

:::note Vault access rules cannot be edited after creation. If your setup changes, create a new service account. :::

Access toggle: Each vault has a toggle to disable service account access in general. It's on by default. Learn more

Rate Limits

Note that rate limits vary by account type (personal, family, teams, business).

Troubleshooting

Secret not found

• Verify the secret reference format is correct: op://vault/item/field
• Check that the item exists in the specified vault
• Ensure the field name matches exactly

Permission denied

• Verify your service account has access to the vault
• Check that the vault allows service account access (toggle in vault settings)
• For desktop app: ensure your user account has access to the vault

Authentication failed (service account)

• Verify the service account token is correct
• Check if the token has been revoked
• Ensure the service account hasn't been disabled

Desktop app authentication failed

• Ensure the op CLI is installed and in your $PATH
• Verify desktop app integration is enabled in 1Password settings
• Check that you specified the correct account (run op account list)
• Try running op whoami to debug CLI connection

Connect server errors

• Verify the Connect server URL is correct and the server is running
• Check that the Connect token has access to the required vault(s)
• Ensure the Connect server version supports the vaults and items you're accessing
• Try accessing <connectHost>/v1/vaults directly to verify connectivity

Rate limiting

• Check your account type's rate limits
• Consider implementing caching or reducing request frequency
• For high-volume use cases, consider upgrading to a business account

Resources

• 1Password
• Service Accounts
• 1Password Connect
• 1Password CLI
• Secret References
• Full documentation