go-pbolt

module
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT

README

go-passbolt

Go Reference

A Go module to interact with Passbolt, an open-source password manager for teams

There also is a CLI Tool to interact with Passbolt using this module here.

Both Passbolt Community and PRO servers are supported.

This module is divided into two packages: API and helper.

In the API package, you will find everything to directly interact with the API.

The helper package has simplified functions that use the API package to perform common but complicated tasks such as sharing a password.

To use the API package, please read the Passbolt API docs. Sadly the docs aren't complete so many things here have been found by looking at the source of Passbolt or through trial and error. If you have a question just ask.

PR's are welcome. But be gentle: if it's something bigger or fundamental: please create an issue and ask first.

API Compatibility

The Go module is designed to work with the latest Passbolt API version, and we strongly recommend keeping your API up to date.

[!IMPORTANT] Compatibility is currently tested with Passbolt API 5.6.1 and later. Older versions are unsupported and may not work.

Support for 5.6.1 is not guaranteed indefinitely and the minimum supported API version may increase in future releases.

In addition, users should also make sure they are running the latest version of the module. A current client stays compatible with supported older API versions, but an older client is not guaranteed to work against a newer API.

Install

go get github.com/pbolt-dev/go-pbolt

Examples

Login

First, you will need to create a client and then log in on the server using the client:

package main

import (
	"context"
	"fmt"

	"github.com/pbolt-dev/go-pbolt/api"
)

const address = "https://passbolt.example.com"
const userPassword = "aStrongPassword"
const userPrivateKey = `
-----BEGIN PGP PRIVATE KEY BLOCK-----
Version: OpenPGP.js v4.6.2
Comment: https://openpgpjs.org
klasd...
-----END PGP PRIVATE KEY BLOCK-----`

func main() {
	client, err := api.NewClient(nil, "", address, userPrivateKey, userPassword)
	if err != nil {
		panic(err)
	}

    	ctx := context.TODO()

	err = client.Login(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Println("Logged in!")
}

Note: if you want to use the client for a long time then you'll have to make sure it is still logged in.

You can do this using the client.CheckSession() function.

Create a Resource

Creating a resource using the helper package is simple. First, add "github.com/pbolt-dev/go-pbolt/helper" to your imports.

Then you can simply:

resourceID, err := helper.CreateResource(
	ctx,                        // Context
	client,                     // API Client
	"",                         // ID of Parent Folder
	"Example Account",          // Name
	"user123",                  // Username
	"https://test.example.com", // URI
	"securePassword123",        // Password
	"This is an Account for the example test portal", // Description
)

Creating a (legacy) resource without the helper package would look like this:

enc, err := client.EncryptMessage("securePassword123")
if err != nil {
	panic(err)
}

res := api.Resource{
	Name:           "Example Account",
	Username:       "user123",
	URI:            "https://test.example.com",
	Description:    "This is an Account for the example test portal",
	Secrets: []api.Secret{
		{Data: enc},
	},
}

resource, err := client.CreateResource(ctx, res)
if err != nil {
	panic(err)
}

Note: Since Passbolt v3 there are resource types. This manual example creates a "password-string" type password where the description is unencrypted. Read more here.

Getting

Generally, API GET calls will have parameters that allow specifying filters and contains, if you don't want to define those parameters just pass nil.

Filters just filter by whatever is given, contains on the other hand specify what information you want to include in the response. Many filters and contains are undocumented in the Passbolt docs.

Here we specify that we want to filter by favorites and that the response should contain the permissions for each resource:

favorites, err := client.GetResources(ctx, &api.GetResourcesOptions{
	FilterIsFavorite: true,
    ContainPermissions: true,
})

We can do the same for users:

users, err := client.GetUsers(ctx, &api.GetUsersOptions{
	FilterSearch:        "Samuel",
	ContainLastLoggedIn: true,
})

Groups:

groups, err := client.GetGroups(ctx, &api.GetGroupsOptions{
    FilterHasUsers: []string{"id of user", "id of other user"},
	ContainUser: true,
})

And also for folders:

folders, err := client.GetFolders(ctx, &api.GetFolderOptions{
	FilterSearch:             "Test Folder",
	ContainChildrenResources: true,
})

Getting by ID is also supported using the singular form:

resource, err := client.GetResource(ctx, "resource ID")

Since the password is encrypted (and sometimes the description too) the helper package has a function to decrypt all encrypted fields automatically:

folderParentID, name, username, uri, password, description, err := helper.GetResource(ctx, client, "resource id")

Updating

The helper package has a function to save you from dealing with resource types when updating a resource:

err = helper.UpdateResource(
	ctx,           // Context
	client,        // API Client
	"id",          // Resource ID
	"name",        // Name
	"username",    // Username
	"url",         // URI
	"strong",      // Password
	"very strong", // Description
)

The same goes for Groups:

err = helper.UpdateGroup(
	ctx,    // Context
	client, // API Client
	"id",   // Group ID
	"name", // Group Name
	[]helper.GroupMembershipOperation{
		{
			UserID:         "id",  // ID of User to Add/Modify/Delete
			IsGroupManager: true,  // Should User be a Group Manager
			Delete:         false, // Should this User be Remove from the Group
		},
	}
)

And for Users:

err = helper.UpdateUser(
	ctx,         // Context
	client,      // API Client
	"id",        // User ID
	"user",      // Role (user or admin)
	"firstname", // FirstName
	"lastname",  // LastName
)

Note: These helpers will only update fields that are not "".

Helper update functions also exists for Folders.

Sharing

As sharing resources is very complicated there are multiple helper functions.

During sharing you will encounter the permission type.

The permissionType can be:

Code Meaning
1 "Read-only"
7 "Can update"
15 "Owner"
-1 Delete existing permission

The ShareResourceWithUsersAndGroups function shares the resource with all provided users and groups with the given permissionType.

err := helper.ShareResourceWithUsersAndGroups(ctx, client, "resource id", []string{"user 1 id"}, []string{"group 1 id"}, 7)

Note: Existing permission of users and groups will be adjusted to be of the provided permissionType.

If you need to do something more complicated like setting users/groups to different types then you can use ShareResource directly:

changes := []helper.ShareOperation{}

// Make this user Owner
changes = append(changes, ShareOperation{
	Type:  15,
	ARO:   "User",
	AROID: "user 1 id",
})

// Make this user "Can Update"
changes = append(changes, ShareOperation{
	Type:  5,
	ARO:   "User",
	AROID: "user 2 id",
})

// Delete this users current permission
changes = append(changes, ShareOperation{
	Type:  -1,
	ARO:   "User",
	AROID: "user 3 id",
})

// Make this group "Read-only"
changes = append(changes, ShareOperation{
	Type:  1,
	ARO:   "Group",
	AROID: "group 1 id",
})

err := helper.ShareResource(ctx, c, resourceID, changes)

Note: These functions are also available for folders

Moving

In Passbolt there are folders, during the creation of resources and folders you can specify in which folder you want to create the resource/folder inside. But if you want to change which folder the resource/folder is in then you can't use the Update function (it is/was possible to update the parent folder using the Update function but that breaks things). Instead, you use the Move function.

err := client.MoveResource(ctx, "resource id", "parent folder id")
err := client.MoveFolder(ctx, "folder id", "parent folder id")

Setup

You can setup a Account using a Invite Link like this:

// Get the UserID and Token from the Invite Link
userID, token, err := ParseInviteUrl(url)

// Make a Client for Registration
rClient, err := api.NewClient(nil, "", "https://localhost", "", "")

// Complete Account Setup
privkey, err := SetupAccount(ctx, rClient, userID, token, "password123")

Verification

You can Verify that the Server hasen't changed, for that you need to initially setup the Verification and save the returned values. Then you can Verify that the serverkey hasen't changed since you setup the Verification. Note this Only Works if the client is not logged in.

// Setup the Verification
token, encToken, err := client.SetupServerVerification(ctx)
if err != nil {
	panic(err)
}
// You Need to save these
fmt.Println("Token: ", token)
fmt.Println("enc Token: ", encToken)
// Now you can Verify the Server
err = client.VerifyServer(ctx, token, encToken)
if err != nil {
	panic(err)
}

MFA

go-passbolt now supports MFA! You can set it up using the Client's MFACallback function, it will provide everything you need to complete any MFA challenges. When your done you just need to return the new MFA Cookie (usually called passbolt_mfa). The helper package has a example implementation for a noninteractive TOTP Setup under helper/mfa.go in the function AddMFACallbackTOTP.

Other

These examples are just the main use cases of these Modules, many more API calls are supported. Look at the reference for more information.

Full Example

This example:

  1. Creates a resource;
  2. Searches for a user named "Test User";
  3. Checks that it's not itself; and,
  4. Shares the password with the "Test User" if necessary:
package main

import (
	"context"
	"fmt"

	"github.com/pbolt-dev/go-pbolt/api"
	"github.com/pbolt-dev/go-pbolt/helper"
)

const address = "https://passbolt.example.com"
const userPassword = "aStrongPassword"
const userPrivateKey = `
-----BEGIN PGP PRIVATE KEY BLOCK-----
Version: OpenPGP.js v4.6.2
Comment: https://openpgpjs.org
klasd...
-----END PGP PRIVATE KEY BLOCK-----`

func main() {
	ctx := context.TODO()

	client, err := api.NewClient(nil, "", address, userPrivateKey, userPassword)
	if err != nil {
		panic(err)
	}

	err = client.Login(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Println("Logged in!")

	resourceID, err := helper.CreateResource(
		ctx,                        // Context
		client,                     // API Client
		"",                         // ID of Parent Folder
		"Example Account",          // Name
		"user123",                  // Username
		"https://test.example.com", // URI
		"securePassword123",        // Password
		"This is an Account for the example test portal", // Description
	)
	if err != nil {
		panic(err)
	}

	fmt.Println("Created Resource")

	users, err := client.GetUsers(ctx, &api.GetUsersOptions{
		FilterSearch: "Test User",
	})
	if err != nil {
		panic(err)
	}

	if len(users) == 0 {
		panic("Cannot Find Test User")
	}

	if client.GetUserID() == users[0].ID {
		fmt.Println("I am the Test User, No Need to Share Password With myself")
        	client.Logout(ctx)
		return
	}

	helper.ShareResourceWithUsersAndGroups(ctx, client, resourceID, []string{users[0].ID}, []string{}, 7)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Shared Resource With Test User %v\n", users[0].ID)

    	client.Logout(ctx)
}

Organization settings

GetOrganizationSettings, SetOrganizationSettings and DeleteOrganizationSettings use the named plugin's organization settings API. OrganizationSettingsPlugins() lists supported names and operations without contacting a server. Available operations also depend on the server edition, enabled plugins and the current user's permissions.

settings, err := client.GetOrganizationSettings(ctx, "email-notifications")
updated, err := client.SetOrganizationSettings(ctx, "email-notifications",
    json.RawMessage(`{"send":{"admin":{"user":{"create":false}}}}`))

Settings and responses use the plugin's original JSON schema. Read responses can include server-only fields and are not necessarily suitable for direct reuse as update input. Values such as false, null and large integers are preserved. Prepare any encrypted or signed credentials before submitting a payload. SSO writes create settings; activation is a separate server workflow. These methods do not perform metadata migrations. Log in again after changing settings to refresh the client's cached metadata and password-expiry settings.

Supported plugins:

Plugin Read Write Delete
account-recovery-policies yes yes —
directory-sync yes yes singleton
email-notifications yes yes —
export-policies yes — —
locale — yes —
metadata-keys yes yes —
metadata-types yes yes —
mfa yes yes —
mfa-policies yes yes —
password-expiry yes yes settings UUID
password-policies yes yes —
scim yes yes settings UUID
secret-revisions yes yes singleton
self-registration yes yes settings UUID
smtp yes yes —
sso yes yes settings UUID
user-key-policies yes — —
user-passphrase-policies yes yes —

For singleton deletion pass an empty settings ID. For record-specific deletion, pass the UUID returned by the settings API. Unsupported operations and invalid JSON objects/IDs are rejected before a request is sent.

Group membership reads and updates

GetGroupWithOptions requests associations from a single group view endpoint. helper.GetGroup reads both groups_users and users join-data layouts and returns membership UUIDs separately from user UUIDs. Missing profiles are allowed; missing membership IDs, unknown roles and conflicting identities are errors.

helper.UpdateGroup is idempotent for an existing role or an already absent membership. It rejects contradictory operations for the same user, retains the normal dry-run and shared-secret re-encryption flow, and rereads the group after writing to verify the requested name and memberships. Verification requires permission to read complete membership associations. API and verification errors remain errors; a failed verification can mean the server already applied some changes, so reread the current group before retrying.

Optional user administration details

User responses preserve optional is_mfa_enabled and scim_entry fields. A nil IsMFAEnabled means the API did not disclose the value, rather than MFA being disabled. SCIM linkage stays in its original JSON schema.

GetUserWithOptions can request contain[scim_entry]; the same option exists on GetUsersOptions. User lists can explicitly request MFA state and filter it through FilterIsMFAEnabled. A non-nil filter automatically requests the required MFA contain, including when filtering for false, without changing caller options. These optional operations require the relevant plugins and access rights. User views return MFA state for administrators or the viewed user where supported.

Directories

Path Synopsis
Package api provides a low-level client for the Passbolt API.
Package api provides a low-level client for the Passbolt API.
Package helper provides high-level operations for the Passbolt API.
Package helper provides high-level operations for the Passbolt API.
internal
e2e/server
Package server runs a throwaway Passbolt in Docker for integration tests.
Package server runs a throwaway Passbolt in Docker for integration tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL