bitwarden

@varlock/bitwarden-plugin

This package is a Varlock plugin that enables loading data from Bitwarden into your configuration. It supports both Bitwarden Secrets Manager (via access tokens over the REST API, using @initBitwarden + bitwarden()) and the Bitwarden Password Manager / self-hosted Vaultwarden (via the bw CLI, using @initBwp + bwp()).

See the full documentation for details.

Features

• Zero-config authentication - Just provide your machine account access token
• UUID-based secret access - Fetch secrets by their unique identifiers
• Organization support - Optional organization ID for filtering and management
• Self-hosted Bitwarden support - Configure custom API and identity URLs
• Multiple instances - Connect to different organizations or self-hosted instances
• 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/bitwarden-plugin

And then register the plugin without any version number

# @plugin(@varlock/bitwarden-plugin)

Otherwise just set the explicit version number when you register it

# @plugin(@varlock/bitwarden-plugin@1.2.3)

See our Plugin Guide for more details.

Setup + Auth

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

Basic Setup

For most use cases, you only need to provide the access token:

# @plugin(@varlock/bitwarden-plugin)
# @initBitwarden(accessToken=$BITWARDEN_ACCESS_TOKEN)
# ---

# @type=bitwardenAccessToken @sensitive @internal
BITWARDEN_ACCESS_TOKEN=

How to get an access token:

1. Navigate to your Bitwarden organization's Secrets Manager
2. Go to Machine accounts → Create a new machine account
3. Copy the Access token (displayed only once!)
4. Grant the machine account access to the secrets or projects you need

Self-hosted

For self-hosted Bitwarden instances, you'll need to provide both URLs:

# @initBitwarden(
#   accessToken=$BITWARDEN_ACCESS_TOKEN,
#   apiUrl="https://bitwarden.yourcompany.com/api",
#   identityUrl="https://bitwarden.yourcompany.com/identity"
# )

• apiUrl - API URL for your self-hosted instance (e.g., "https://bitwarden.yourcompany.com/api")
• identityUrl - Identity service URL for your self-hosted instance (e.g., "https://bitwarden.yourcompany.com/identity")

Multiple instances

If you need to connect to multiple organizations or instances, register multiple named instances:

# @initBitwarden(id=prod, accessToken=$PROD_ACCESS_TOKEN)
# @initBitwarden(id=dev, accessToken=$DEV_ACCESS_TOKEN)

Reading secrets

This plugin introduces the bitwarden() function to fetch secret values.

# @plugin(@varlock/bitwarden-plugin)
# @initBitwarden(accessToken=$BITWARDEN_ACCESS_TOKEN)
# ---

# @type=bitwardenAccessToken @sensitive @internal
BITWARDEN_ACCESS_TOKEN=

# Fetch secrets by UUID
DATABASE_URL=bitwarden("12345678-1234-1234-1234-123456789abc")
API_KEY=bitwarden("87654321-4321-4321-4321-cba987654321")

# If using multiple instances
PROD_SECRET=bitwarden(prod, "11111111-1111-1111-1111-111111111111")
DEV_SECRET=bitwarden(dev, "22222222-2222-2222-2222-222222222222")

Finding Secret UUIDs

To find a secret's UUID:

1. Open your Bitwarden Secrets Manager
2. Navigate to the secret
3. Copy the UUID from the URL or secret details (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

---

Password Manager / Vaultwarden

Separate from Secrets Manager, you can load values from your personal/team Bitwarden Password Manager vault — or a self-hosted Vaultwarden server — using the bw CLI. varlock unlocks the vault for you (prompting for your master password on first use) and caches the resulting session token, so you never have to manually unlock and paste a token.

Install the bw CLI from a trusted source and log in once (bw login), then:

# @plugin(@varlock/bitwarden-plugin)
# @initBwp()
# ---

# defaults to the item's password
DATABASE_PASSWORD=bwp("Production DB")
# other fields: username, notes, totp, uri, or a custom field name
# (totp returns the stored TOTP secret/seed, not a generated 6-digit code)
DATABASE_USER=bwp("Production DB", field=username)

The cached session token lives in varlock's encrypted cache (biometric-gated on platforms with a secure enclave) and by default is reused indefinitely (sessionTtl="forever"). The bw CLI session does not auto-lock on system sleep/lock/restart (those are app-only settings), so a fresh master-password unlock is only needed when the session is invalidated externally (bw lock/bw logout, an external bw unlock, or account policy); set a shorter sessionTtl to force periodic re-auth. For CI / non-interactive use, pass a pre-obtained token (@initBwp(sessionToken=$BWP_SESSION)) or a master password (@initBwp(masterPassword=$BW_MASTER_PASSWORD)). To read from multiple accounts/servers, give each instance its own bw data dir (@initBwp(id=work, appDataDir=$BWP_WORK_DIR), with the machine-specific path set in .env.local). See the full docs for all options.

---

Reference

Root decorators

@initBitwarden()

Initialize a Bitwarden Secrets Manager plugin instance.

Parameters:

• accessToken: string (required) - Machine account access token
• apiUrl?: string - API URL for self-hosted Bitwarden (defaults to https://api.bitwarden.com)
• identityUrl?: string - Identity service URL for self-hosted Bitwarden (defaults to https://identity.bitwarden.com)
• cacheTtl?: string | number - Cache resolved values from bitwarden() for the provided TTL ("5m", "1h", "1d", or "forever" to cache until manually cleared); set to false (or an empty string) to disable caching
• id?: string - Instance identifier for multiple instances (defaults to _default)

Functions

bitwarden()

Fetch a secret from Bitwarden Secrets Manager.

Signatures:

• bitwarden(secretId) - Fetch by secret UUID from default instance
• bitwarden(instanceId, secretId) - Fetch from a specific instance

Secret ID Format:

• Must be a valid UUID: "12345678-1234-1234-1234-123456789abc"

Data Types

• bitwardenAccessToken - Machine account access token (sensitive)
• bitwardenSecretId - Secret UUID (validated format)
• bitwardenOrganizationId - Organization UUID (validated format)

---

Bitwarden Setup

Create a Machine Account

Machine accounts provide programmatic access to Bitwarden Secrets Manager.

Using the Web Vault:

1. Log in to your Bitwarden organization
2. Navigate to Secrets Manager → Machine accounts
3. Click New machine account
4. Provide a name (e.g., "Production App")
5. Copy the Access token (shown only once!)
6. Grant access to specific projects or secrets

Permission Levels:

• Can read - Retrieve secrets only
• Can read, write - Retrieve, create, and edit secrets

Important: Store the access token securely - it will only be displayed once!

Grant Access to Secrets

Via Projects:

1. Create or select a project in Secrets Manager
2. Add secrets to the project
3. Grant your machine account access to the project

Direct Secret Access:

1. Navigate to a specific secret
2. Click Access
3. Add your machine account with appropriate permissions

Find Your Organization ID

# Via Bitwarden CLI
bw org list

# Or check your organization's URL
https://vault.bitwarden.com/#/organizations/{organization-id}

Troubleshooting

Secret not found

• Verify the secret UUID is correct (must be valid UUID format)
• Check that the secret exists in your Bitwarden Secrets Manager
• Ensure your machine account has access to the secret or its project

Permission denied

• Verify your machine account has "Can read" or "Can read, write" permissions
• Check that the machine account has access to the specific secret
• Review the access settings in Bitwarden Secrets Manager console

Authentication failed

• Verify the access token is correct
• Check if the access token has been revoked or expired
• Ensure the machine account is not disabled
• For self-hosted: verify apiUrl and identityUrl are correct

Invalid UUID format

• Secret IDs must be valid UUIDs: 12345678-1234-1234-1234-123456789abc
• Check for typos or incorrect format
• UUIDs should contain 32 hexadecimal characters and 4 hyphens

Resources

• Bitwarden Secrets Manager
• Machine Accounts Documentation
• Self-Hosting Bitwarden