Passbolt Plugin

Our Passbolt plugin enables secure loading of secrets from Passbolt password manager using declarative instructions within your .env files.

Passbolt is an open-source, self-hosted password manager built for teams. This plugin connects to your Passbolt instance’s API using your account kit and passphrase, decrypting secrets via OpenPGP.

Features

• Account kit authentication — just provide your account kit and passphrase
• UUID-based secret access — fetch secrets by their resource UUID
• #field syntax — read specific fields (username, password, URI, TOTP, custom fields)
• Bulk loading with passboltBulk() to load all passwords from a folder
• Custom fields object with passboltCustomFieldsObj() for @setValuesBulk
• Self-hosted support — API URL is read from your account kit
• Multiple instances — connect to different Passbolt instances

Installation and setup

In a JS/TS project, you may install the @varlock/passbolt-plugin package as a normal dependency. Otherwise you can just load it directly from your .env.schema file, as long as you add a version specifier. See the plugins guide for more instructions on installing plugins.

.env.schema

# 1. Load the plugin
# @plugin(@varlock/passbolt-plugin)
#
# 2. Initialize the plugin - see below for auth setup
# @initPassbolt(accountKit=$PB_ACCOUNT_KIT, passphrase=$PB_PASSPHRASE)
# ---

# 3. Add config items for your credentials
# @type=passboltAccountKit @sensitive
PB_ACCOUNT_KIT=
# @sensitive
PB_PASSPHRASE=

Authentication setup

The plugin authenticates using your Passbolt account kit (a base64-encoded bundle containing your server URL, keys, and user info) and your passphrase (used to decrypt your private key).

1. Download your account kit from Passbolt:

   • Open your Passbolt instance
   • Navigate to Manage account → Desktop app setup
   • Click Download your account kit and copy the base64 contents

2. Wire up your credentials in the schema:

   .env.schema

   # @plugin(@varlock/passbolt-plugin)
   # @initPassbolt(accountKit=$PB_ACCOUNT_KIT, passphrase=$PB_PASSPHRASE)
   # ---
   # @type=passboltAccountKit @sensitive
   PB_ACCOUNT_KIT=
   # @sensitive
   PB_PASSPHRASE=

3. Set your credentials in deployed environments. Copy the account kit and passphrase values and set them using your platform’s env var management UI.

Multiple instances

If you need to connect to multiple Passbolt instances or users, register named instances using the id parameter:

.env.schema

# @initPassbolt(id=prod, accountKit=$PROD_ACCOUNT_KIT, passphrase=$PROD_PASSPHRASE)
# @initPassbolt(id=dev, accountKit=$DEV_ACCOUNT_KIT, passphrase=$DEV_PASSPHRASE)

Loading secrets

Once the plugin is installed and initialized, you can start adding config items that load values from Passbolt using the passbolt() resolver function.

Basic usage

Fetch secrets by resource UUID. By default, the password field is returned:

.env.schema

# Fetch password (default field) by resource UUID
DB_PASSWORD=passbolt("01234567-0123-4567-890a-bcdef0123456")
API_KEY=passbolt("76543210-3210-4321-a098-ba9876543210")

Fetching specific fields

Use #field syntax to fetch a specific field from a resource:

.env.schema

# Built-in fields
LOGIN_URI=passbolt("01234567-0123-4567-890a-bcdef0123456#uri")
LOGIN_USER=passbolt("01234567-0123-4567-890a-bcdef0123456#username")
LOGIN_PASS=passbolt("01234567-0123-4567-890a-bcdef0123456#password")

# TOTP fields
TOTP_SECRET=passbolt("01234567-0123-4567-890a-bcdef0123456#totp.secret")
TOTP_CODE=passbolt("01234567-0123-4567-890a-bcdef0123456#totp.code")

# Custom fields — any unrecognized name is treated as a custom field
MY_FIELD=passbolt("01234567-0123-4567-890a-bcdef0123456#MyCustomField")

Alternatively, use the named field parameter:

.env.schema

LOGIN_PASS=passbolt("01234567-0123-4567-890a-bcdef0123456", field="password")
CUSTOM=passbolt("01234567-0123-4567-890a-bcdef0123456", field="AnotherField")

Using multiple instances

When multiple plugin instances are initialized, pass the instance ID as the first argument:

.env.schema

PROD_SECRET=passbolt(prod, "11111111-1111-4111-a111-111111111111")
DEV_SECRET=passbolt(dev, "22222222-2222-4222-b222-222222222222")

Bulk loading from a folder

Use passboltBulk() with @setValuesBulk to load all passwords from a Passbolt folder at once. Resources are matched by name:

.env.schema

# @plugin(@varlock/passbolt-plugin)
# @initPassbolt(accountKit=$PB_ACCOUNT_KIT, passphrase=$PB_PASSPHRASE)
# @setValuesBulk(passboltBulk(folderPath="Database/Dev"))
# ---
# @type=passboltAccountKit @sensitive
PB_ACCOUNT_KIT=
# @sensitive
PB_PASSPHRASE=

# These will be populated from Passbolt (matched by resource name)
API_KEY=
DB_PASSWORD=

Bulk loading custom fields

Use passboltCustomFieldsObj() with @setValuesBulk to load all custom fields from a single resource:

.env.schema

# @setValuesBulk(passboltCustomFieldsObj("01234567-0123-4567-890a-bcdef0123456"))
# ---

# These will be populated from custom field names
API_KEY=
DB_PASSWORD=

Finding resource UUIDs

To find a resource’s UUID:

1. Open your Passbolt instance
2. Navigate to the resource
3. Copy the UUID from the URL (format: xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx)

---

Reference

Root decorators

@initPassbolt()

Initializes an instance of the Passbolt plugin — setting up authentication and options. Can be called multiple times for different instances.

Key/value args:

• accountKit (required): Passbolt account kit (base64-encoded). Should be a reference to a config item of type passboltAccountKit.
• passphrase (required): Passphrase to decrypt your private key. Should be a reference to a sensitive config item.
• id (optional): instance identifier for multiple instances

# @initPassbolt(accountKit=$PB_ACCOUNT_KIT, passphrase=$PB_PASSPHRASE)
# ---
# @type=passboltAccountKit @sensitive
PB_ACCOUNT_KIT=
# @sensitive
PB_PASSPHRASE=

Data types

passboltAccountKit

Represents a Passbolt account kit (base64-encoded). Validation ensures the value is valid base64. The type is marked as @sensitive, so adding an explicit @sensitive decorator is optional.

# @type=passboltAccountKit @sensitive
PB_ACCOUNT_KIT=

Resolver functions

passbolt()

Fetches a field from a Passbolt resource. Returns the password field by default.

Array args:

• instanceId (optional): instance identifier when multiple plugin instances are initialized
• resourceId: UUID of the resource to fetch. Supports #field suffix for field extraction.

Key/value args:

• field (optional): alternative to #field syntax for specifying which field to read

Built-in fields: password (default), username, uri, totp.secret, totp.code. Any other name is treated as a custom field.

# Default password field
SECRET=passbolt("01234567-0123-4567-890a-bcdef0123456")

# Specific field via #field
USER=passbolt("01234567-0123-4567-890a-bcdef0123456#username")

# Named field parameter
USER=passbolt("01234567-0123-4567-890a-bcdef0123456", field="username")

# With instance ID
SECRET=passbolt(prod, "01234567-0123-4567-890a-bcdef0123456")

passboltBulk()

Loads all passwords from a Passbolt folder as a JSON map keyed by resource name. Intended for use with @setValuesBulk.

Array args:

• instanceId (optional): instance identifier when multiple plugin instances are initialized

Key/value args:

• folderPath (required): folder path to load resources from. Use / to separate nested folders (escape literal / in names with \).

# Load from a folder
# @setValuesBulk(passboltBulk(folderPath="Production"))

# Nested folder
# @setValuesBulk(passboltBulk(folderPath="Production/Database"))

# With instance ID
# @setValuesBulk(passboltBulk(prod, folderPath="Production"))

passboltCustomFieldsObj()

Fetches all custom fields from a Passbolt resource as a JSON object. Intended for use with @setValuesBulk.

Array args:

• instanceId (optional): instance identifier when multiple plugin instances are initialized
• resourceId: UUID of the resource

# Load custom fields from a resource
# @setValuesBulk(passboltCustomFieldsObj("01234567-0123-4567-890a-bcdef0123456"))

# With instance ID
# @setValuesBulk(passboltCustomFieldsObj(prod, "01234567-0123-4567-890a-bcdef0123456"))

---

Troubleshooting

Authentication failed

• Verify the account kit is correct (must be valid base64)
• Ensure the passphrase matches the one used when the account was created

Resource not found

• Verify the resource UUID is correct (must be valid UUID v4 format)
• Check that the resource exists in your Passbolt instance
• Ensure the resource is shared with your user

Folder not found

• Check that the folder path is correct and exists
• Folder paths are case-sensitive
• Use / to separate nested folders

Resources

• Passbolt — open-source password manager for teams
• Passbolt Help — official documentation
• Passbolt Community — community forums