go.bigb.es/go-bitwarden

v1.0.0
Doc Versions Source

Documentation

Package bitwarden provides a comprehensive Go client library for Bitwarden and Vaultwarden password managers. It supports both CLI-based communication (via bw serve) and direct server communication with end-to-end encryption.

The library provides two client modes:

  • Client: Communicates via Bitwarden CLI's "bw serve" API (requires running CLI)
  • DirectClient: Direct server communication with full encryption support (no CLI needed)

Both clients implement the VaultClient interface, providing a unified API for vault operations including items, folders, collections, organizations, Send, and attachments.

Basic usage with Client: 

client := bitwarden.NewClient()
err := client.Unlock(context.Background(), "master-password")
items, _ := client.Items().List(context.Background(), nil)

Basic usage with DirectClient: 

client := bitwarden.NewDirectClient(
    "https://vault.bitwarden.com",
    "user@example.com",
    "master-password",
)
err := client.Unlock(context.Background(), "master-password")
client.Sync(context.Background())
items, _ := client.Items().List(context.Background(), nil)

Index

Types

T type APIError

src 
type APIError struct {
	StatusCode int
	Message    string
}

APIError represents an error response from the bw serve API.

m func (*APIError) Error

src 
func (e *APIError) Error() string

T type Attachment

src 
type Attachment struct {
	ID       string `json:"id"`
	FileName string `json:"fileName"`
	Size     string `json:"size"`
	SizeName string `json:"sizeName"`
	URL      string `json:"url"`
}

Attachment represents a file attachment on a vault item.

T type AttachmentsAPI

src 
type AttachmentsAPI interface {
	// Create uploads a file attachment to a vault item.
	Create(ctx context.Context, itemID, filename string, file io.Reader) (*Item, error)

	// Get downloads a file attachment's contents.
	Get(ctx context.Context, attachmentID, itemID string) ([]byte, error)

	// Delete removes a file attachment from a vault item.
	Delete(ctx context.Context, attachmentID, itemID string) error
}

AttachmentsAPI defines operations on file attachments for vault items.

T type AttachmentsService

src 
type AttachmentsService struct {
	// contains filtered or unexported fields
}

AttachmentsService handles file attachment operations.

m func (*AttachmentsService) Create

src 
func (s *AttachmentsService) Create(ctx context.Context, itemID, filename string, file io.Reader) (*Item, error)

Create uploads a file attachment to a vault item.

m func (*AttachmentsService) Delete

src 
func (s *AttachmentsService) Delete(ctx context.Context, attachmentID, itemID string) error

Delete removes an attachment by ID from a vault item.

m func (*AttachmentsService) Get

src 
func (s *AttachmentsService) Get(ctx context.Context, attachmentID, itemID string) ([]byte, error)

Get downloads an attachment by ID from a vault item. Returns the raw file contents.

T type Card

src 
type Card struct {
	CardholderName string `json:"cardholderName,omitempty"`
	Brand          string `json:"brand,omitempty"`
	Number         string `json:"number,omitempty"`
	ExpMonth       string `json:"expMonth,omitempty"`
	ExpYear        string `json:"expYear,omitempty"`
	Code           string `json:"code,omitempty"`
}

Card represents card-specific fields of a vault item.

T type Client

src 
type Client struct {
	// contains filtered or unexported fields
}

Client provides access to a Bitwarden vault via the bw serve API. It requires the Bitwarden CLI to be running in serve mode (bw serve). Client implements the VaultClient interface.

For direct server communication without the CLI, use DirectClient instead.

f func NewClient

src 
func NewClient(opts ...ClientOption) *Client

NewClient creates a new Bitwarden vault management client that communicates via the bw serve API. The client is created in a locked state and must be unlocked using Unlock() before accessing vault data.

Options can be provided to customize the client behavior: 

client := bitwarden.NewClient(
    bitwarden.WithBaseURL("http://localhost:8087"),
    bitwarden.WithHTTPClient(customHTTPClient),
)

m func (*Client) Attachments

src 
func (c *Client) Attachments() AttachmentsAPI

Attachments returns the attachments service for file attachment operations.

m func (*Client) Collections

src 
func (c *Client) Collections() CollectionsAPI

Collections returns the collections service for accessing user collections.

m func (*Client) Folders

src 
func (c *Client) Folders() FoldersAPI

Folders returns the folders service for organizing vault items.

m func (*Client) Generate

src 
func (c *Client) Generate(ctx context.Context, opts GenerateOptions) (string, error)

Generate generates a password or passphrase based on the provided options. Use GenerateOptions to configure password length, character sets, or passphrase settings.

m func (*Client) Items

src 
func (c *Client) Items() ItemsAPI

Items returns the vault items (ciphers) service for CRUD operations on vault items.

m func (*Client) Lock

src 
func (c *Client) Lock(ctx context.Context) error

Lock locks the vault, clearing encryption keys from memory. After locking, Unlock must be called before accessing vault data.

m func (*Client) OrgCollections

src 
func (c *Client) OrgCollections() OrgCollectionsAPI

OrgCollections returns the organization collections service for managing org collections.

m func (*Client) OrgMembers

src 
func (c *Client) OrgMembers() OrgMembersAPI

OrgMembers returns the organization members service for member management.

m func (*Client) Organizations

src 
func (c *Client) Organizations() OrganizationsAPI

Organizations returns the organizations service for listing user organizations.

m func (*Client) Send

src 
func (c *Client) Send() SendAPI

Send returns the Bitwarden Send service for creating secure shares.

m func (*Client) Status

src 
func (c *Client) Status(ctx context.Context) (*Status, error)

Status returns the current status of the Bitwarden CLI including lock state, user information, and server URL.

m func (*Client) Sync

src 
func (c *Client) Sync(ctx context.Context) error

Sync triggers a vault synchronization with the server. This downloads the latest vault data and updates the local cache.

m func (*Client) Unlock

src 
func (c *Client) Unlock(ctx context.Context, password string) error

Unlock unlocks the vault with the given master password. The vault must be unlocked before accessing any vault data.

T type ClientOption

src 
type ClientOption func(*Client)

ClientOption configures the Client using the functional options pattern.

f func WithBaseURL

src 
func WithBaseURL(u string) ClientOption

WithBaseURL sets the base URL for the bw serve API. Default is "http://localhost:8087".

f func WithHTTPClient

src 
func WithHTTPClient(hc *http.Client) ClientOption

WithHTTPClient sets a custom http.Client for API requests. Use this to configure timeouts, proxies, or custom transport.

T type Collection

src 
type Collection struct {
	Object         string `json:"object,omitempty"`
	ID             string `json:"id,omitempty"`
	OrganizationID string `json:"organizationId,omitempty"`
	Name           string `json:"name"`
	ExternalID     string `json:"externalId,omitempty"`
}

Collection represents a vault collection.

T type CollectionsAPI

src 
type CollectionsAPI interface {
	// List retrieves collections visible to the user with optional filtering.
	List(ctx context.Context, organizationID, search string) ([]Collection, error)

	// Get retrieves a single collection by its ID.
	Get(ctx context.Context, id string) (*Collection, error)
}

CollectionsAPI defines read-only operations on user collections. Collections are groups of items owned by organizations.

T type CollectionsService

src 
type CollectionsService struct {
	// contains filtered or unexported fields
}

CollectionsService handles collection operations (read-only for user collections).

m func (*CollectionsService) Get

src 
func (s *CollectionsService) Get(ctx context.Context, id string) (*Collection, error)

Get returns a single collection by ID.

m func (*CollectionsService) List

src 
func (s *CollectionsService) List(ctx context.Context, organizationID, search string) ([]Collection, error)

List returns all collections, optionally filtered.

T type ConfirmRequest

src 
type ConfirmRequest struct {
	OrganizationID string `json:"organizationId"`
}

ConfirmRequest is the body for POST /confirm/org-member/:id.

T type DirectAttachmentsService

src 
type DirectAttachmentsService struct {
	// contains filtered or unexported fields
}

DirectAttachmentsService handles attachment operations via the direct server API.

m func (*DirectAttachmentsService) Create

src 
func (s *DirectAttachmentsService) Create(ctx context.Context, itemID, filename string, file io.Reader) (*Item, error)

m func (*DirectAttachmentsService) Delete

src 
func (s *DirectAttachmentsService) Delete(ctx context.Context, attachmentID, itemID string) error

m func (*DirectAttachmentsService) Get

src 
func (s *DirectAttachmentsService) Get(ctx context.Context, attachmentID, itemID string) ([]byte, error)

T type DirectClient

src 
type DirectClient struct {
	// contains filtered or unexported fields
}

DirectClient communicates directly with a Bitwarden/Vaultwarden server, handling authentication and end-to-end encryption entirely in Go without requiring the Bitwarden CLI. This is useful for applications that need to integrate Bitwarden functionality without external dependencies.

DirectClient implements the VaultClient interface and provides full access to vault operations including items, folders, collections, organizations, Send, and attachments.

Security considerations:

  • The master password is kept in memory for re-authentication
  • Encryption keys are derived from the master password using PBKDF2 or Argon2id
  • All vault data is encrypted/decrypted locally
  • Keys can be cleared from memory using Lock()

f func NewDirectClient

src 
func NewDirectClient(serverURL, email, password string, opts ...DirectClientOption) *DirectClient

NewDirectClient creates a new client that communicates directly with the Bitwarden/Vaultwarden server without requiring the CLI. The client handles authentication and end-to-end encryption automatically.

Parameters:

  • serverURL: The base URL of the Bitwarden/Vaultwarden server (e.g., "https://vault.bitwarden.com")
  • email: The user's email address for authentication
  • password: The master password for vault decryption
  • opts: Optional configuration using With* functions

The client is created in a locked state. Call Login() first, then Unlock() or call Unlock() directly which handles both authentication and key derivation.

Example: 

client := bitwarden.NewDirectClient(
    "https://vault.bitwarden.com",
    "user@example.com",
    "master-password",
    bitwarden.WithTwoFactorProvider(my2FAHandler),
)
err := client.Unlock(context.Background(), "master-password")
client.Sync(context.Background())

m func (*DirectClient) Attachments

src 
func (dc *DirectClient) Attachments() AttachmentsAPI

Attachments returns the attachments service for file attachment operations.

m func (*DirectClient) Collections

src 
func (dc *DirectClient) Collections() CollectionsAPI

Collections returns the collections service for accessing user collections.

m func (*DirectClient) Folders

src 
func (dc *DirectClient) Folders() FoldersAPI

Folders returns the folders service for organizing vault items.

m func (*DirectClient) Generate

src 
func (dc *DirectClient) Generate(ctx context.Context, opts GenerateOptions) (string, error)

Generate generates a password or passphrase locally using cryptographically secure random number generation. This does not require server communication. Use GenerateOptions to configure the password complexity or passphrase settings.

m func (*DirectClient) GetAPIKey

src 
func (dc *DirectClient) GetAPIKey(ctx context.Context) (clientID, clientSecret string, err error)

GetAPIKey retrieves an API key for the current user. The client must be logged in (have a valid access token). The API key can be used for authenticating without 2FA in automated environments.

Returns:

  • clientID: The API key identifier (typically "user.<uuid>")
  • clientSecret: The API key secret

m func (*DirectClient) Items

src 
func (dc *DirectClient) Items() ItemsAPI

Items returns the vault items (ciphers) service for CRUD operations on vault items.

m func (*DirectClient) Lock

src 
func (dc *DirectClient) Lock(ctx context.Context) error

Lock clears the encryption keys and cached vault data from memory. If real-time notifications are running, they are stopped. After locking, Unlock must be called before accessing vault data again.

m func (*DirectClient) Login

src 
func (dc *DirectClient) Login(ctx context.Context) error

Login authenticates with the Bitwarden server using the configured credentials. This must be called before other operations (or use Unlock which calls Login internally).

If an API key was configured via WithAPIKey, it uses client_credentials grant which bypasses 2FA requirements. Otherwise, it uses the standard password grant which may trigger the 2FA callback if two-factor is enabled on the account.

After successful login, the encryption keys are available but the vault data still needs to be synced using Sync().

m func (*DirectClient) OrgCollections

src 
func (dc *DirectClient) OrgCollections() OrgCollectionsAPI

OrgCollections returns the organization collections service for managing org collections.

m func (*DirectClient) OrgMembers

src 
func (dc *DirectClient) OrgMembers() OrgMembersAPI

OrgMembers returns the organization members service for member management.

m func (*DirectClient) Organizations

src 
func (dc *DirectClient) Organizations() OrganizationsAPI

Organizations returns the organizations service for listing user organizations.

m func (*DirectClient) Register

src 
func (dc *DirectClient) Register(ctx context.Context, name string, cfg crypto.DeriveKeyConfig) error

Register creates a new Bitwarden account on the server. This is typically only used for testing or automated account provisioning. The cfg parameter specifies the key derivation function configuration (PBKDF2 or Argon2id).

m func (*DirectClient) Send

src 
func (dc *DirectClient) Send() SendAPI

Send returns the Bitwarden Send service for creating secure shares.

m func (*DirectClient) ServerURL

src 
func (dc *DirectClient) ServerURL() string

ServerURL returns the configured Bitwarden/Vaultwarden server URL.

m func (*DirectClient) SetNotificationsLogger

src 
func (dc *DirectClient) SetNotificationsLogger(l *log.Logger)

SetNotificationsLogger sets a logger for notification debug output.

m func (*DirectClient) StartNotifications

src 
func (dc *DirectClient) StartNotifications(ctx context.Context) error

StartNotifications connects to the server's WebSocket notification hub. Notifications trigger automatic cache invalidation. If a NotificationHandler was configured via WithNotificationHandler, it is also called. The provided context controls the connection lifetime.

m func (*DirectClient) Status

src 
func (dc *DirectClient) Status(ctx context.Context) (*Status, error)

Status returns the current client status including lock state, user information, and server URL. This does not require the vault to be unlocked.

m func (*DirectClient) StopNotifications

src 
func (dc *DirectClient) StopNotifications() error

StopNotifications disconnects from the notification hub.

m func (*DirectClient) Sync

src 
func (dc *DirectClient) Sync(ctx context.Context) error

Sync downloads the vault data from the server and decrypts it locally. The vault must be unlocked before calling Sync. After sync, the decrypted data is available through the various service APIs (Items, Folders, etc.).

Sync also loads organization keys and populates the local cache for faster access.

m func (*DirectClient) Unlock

src 
func (dc *DirectClient) Unlock(ctx context.Context, password string) error

Unlock re-authenticates with the server and re-derives the encryption keys from the master password. This combines Login and key derivation into one step.

If 2FA is enabled, the configured TwoFactorProvider callback will be invoked. After unlock, call Sync to download and decrypt the vault data.

T type DirectClientOption

src 
type DirectClientOption func(*DirectClient)

DirectClientOption configures the DirectClient using the functional options pattern.

f func WithAPIKey

src 
func WithAPIKey(clientID, clientSecret string) DirectClientOption

WithAPIKey configures API key authentication using the client_credentials grant. API keys can be generated in the Bitwarden web vault and bypass 2FA requirements, but the master password is still required for vault decryption. The clientID is typically in the format "user.<user_uuid>".

Example: 

client := bitwarden.NewDirectClient(
    serverURL, email, masterPassword,
    bitwarden.WithAPIKey("user.abc-123", "secret-key"),
)

f func WithDeviceInfo

src 
func WithDeviceInfo(name, identifier string, deviceType int) DirectClientOption

WithDeviceInfo sets device information for token requests. This information appears in the Bitwarden account's device list. If not provided, default device info will be used.

f func WithDirectHTTPClient

src 
func WithDirectHTTPClient(hc *http.Client) DirectClientOption

WithDirectHTTPClient sets a custom http.Client for direct server communication. Use this to configure timeouts, proxies, or custom transport.

f func WithIdentityURL

src 
func WithIdentityURL(url string) DirectClientOption

WithIdentityURL sets a separate identity URL for authentication. This is typically used for Bitwarden cloud where identity and API URLs differ. For self-hosted Vaultwarden, this is usually not needed.

f func WithNotificationHandler

src 
func WithNotificationHandler(h NotificationHandler) DirectClientOption

WithNotificationHandler sets a callback invoked on each notification. If not set, notifications only trigger cache invalidation.

f func WithTwoFactorProvider

src 
func WithTwoFactorProvider(p api.TwoFactorProvider) DirectClientOption

WithTwoFactorProvider sets a callback function for handling two-factor authentication. The callback receives the available 2FA providers and should return the selected provider type and code. This is called during Login/Unlock if 2FA is enabled.

T type DirectCollectionsService

src 
type DirectCollectionsService struct {
	// contains filtered or unexported fields
}

DirectCollectionsService handles collection operations via the direct server API.

m func (*DirectCollectionsService) Get

src 
func (s *DirectCollectionsService) Get(ctx context.Context, id string) (*Collection, error)

m func (*DirectCollectionsService) List

src 
func (s *DirectCollectionsService) List(ctx context.Context, organizationID, search string) ([]Collection, error)

T type DirectFoldersService

src 
type DirectFoldersService struct {
	// contains filtered or unexported fields
}

DirectFoldersService handles folder operations via the direct server API.

m func (*DirectFoldersService) Create

src 
func (s *DirectFoldersService) Create(ctx context.Context, folder Folder) (*Folder, error)

m func (*DirectFoldersService) Delete

src 
func (s *DirectFoldersService) Delete(ctx context.Context, id string) error

m func (*DirectFoldersService) Get

src 
func (s *DirectFoldersService) Get(ctx context.Context, id string) (*Folder, error)

m func (*DirectFoldersService) List

src 
func (s *DirectFoldersService) List(ctx context.Context, search string) ([]Folder, error)

m func (*DirectFoldersService) Update

src 
func (s *DirectFoldersService) Update(ctx context.Context, id string, folder Folder) (*Folder, error)

T type DirectItemsService

src 
type DirectItemsService struct {
	// contains filtered or unexported fields
}

DirectItemsService handles vault item operations via the direct server API.

m func (*DirectItemsService) Create

src 
func (s *DirectItemsService) Create(ctx context.Context, item Item) (*Item, error)

m func (*DirectItemsService) Delete

src 
func (s *DirectItemsService) Delete(ctx context.Context, id string) error

m func (*DirectItemsService) Get

src 
func (s *DirectItemsService) Get(ctx context.Context, id string) (*Item, error)

m func (*DirectItemsService) List

src 
func (s *DirectItemsService) List(ctx context.Context, filter ListFilter) ([]Item, error)

m func (*DirectItemsService) Move

src 
func (s *DirectItemsService) Move(ctx context.Context, id, organizationID string, collectionIDs []string) error

m func (*DirectItemsService) Restore

src 
func (s *DirectItemsService) Restore(ctx context.Context, id string) error

m func (*DirectItemsService) Update

src 
func (s *DirectItemsService) Update(ctx context.Context, id string, item Item) (*Item, error)

T type DirectOrgCollectionsService

src 
type DirectOrgCollectionsService struct {
	// contains filtered or unexported fields
}

DirectOrgCollectionsService handles organization collection operations.

m func (*DirectOrgCollectionsService) Create

src 
func (s *DirectOrgCollectionsService) Create(ctx context.Context, collection OrgCollection) (*OrgCollection, error)

m func (*DirectOrgCollectionsService) Delete

src 
func (s *DirectOrgCollectionsService) Delete(ctx context.Context, id string) error

m func (*DirectOrgCollectionsService) Get

src 
func (s *DirectOrgCollectionsService) Get(ctx context.Context, id string) (*OrgCollection, error)

m func (*DirectOrgCollectionsService) List

src 
func (s *DirectOrgCollectionsService) List(ctx context.Context, organizationID string, search string) ([]OrgCollection, error)

m func (*DirectOrgCollectionsService) Update

src 
func (s *DirectOrgCollectionsService) Update(ctx context.Context, id string, collection OrgCollection) (*OrgCollection, error)

T type DirectOrgMembersService

src 
type DirectOrgMembersService struct {
	// contains filtered or unexported fields
}

DirectOrgMembersService handles organization member operations.

m func (*DirectOrgMembersService) Confirm

src 
func (s *DirectOrgMembersService) Confirm(ctx context.Context, id, organizationID string) error

m func (*DirectOrgMembersService) List

src 
func (s *DirectOrgMembersService) List(ctx context.Context, organizationID string) ([]OrgMember, error)

T type DirectOrganizationsService

src 
type DirectOrganizationsService struct {
	// contains filtered or unexported fields
}

DirectOrganizationsService handles organization operations via the direct server API.

m func (*DirectOrganizationsService) Get

src 
func (s *DirectOrganizationsService) Get(ctx context.Context, id string) (*Organization, error)

m func (*DirectOrganizationsService) List

src 
func (s *DirectOrganizationsService) List(ctx context.Context, search string) ([]Organization, error)

T type DirectSendService

src 
type DirectSendService struct {
	// contains filtered or unexported fields
}

DirectSendService handles Send operations via the direct server API.

m func (*DirectSendService) Create

src 
func (s *DirectSendService) Create(ctx context.Context, send Send) (*Send, error)

m func (*DirectSendService) Delete

src 
func (s *DirectSendService) Delete(ctx context.Context, id string) error

m func (*DirectSendService) Get

src 
func (s *DirectSendService) Get(ctx context.Context, id string) (*Send, error)

m func (*DirectSendService) List

src 
func (s *DirectSendService) List(ctx context.Context) ([]Send, error)

m func (*DirectSendService) RemovePassword

src 
func (s *DirectSendService) RemovePassword(ctx context.Context, id string) (*Send, error)

m func (*DirectSendService) Update

src 
func (s *DirectSendService) Update(ctx context.Context, id string, send Send) (*Send, error)

T type Duration

src 
type Duration = time.Duration

Duration alias for convenience.

T type Field

src 
type Field struct {
	Name     string    `json:"name"`
	Value    string    `json:"value"`
	Type     FieldType `json:"type"`
	LinkedID *int      `json:"linkedId,omitempty"`
}

Field represents a custom field on a vault item.

T type FieldType

src 
type FieldType int

FieldType represents the type of a custom field. 

const (
	FieldTypeText    FieldType = 0
	FieldTypeHidden  FieldType = 1
	FieldTypeBoolean FieldType = 2
	FieldTypeLinked  FieldType = 3
)

T type Folder

src 
type Folder struct {
	Object string `json:"object,omitempty"`
	ID     string `json:"id,omitempty"`
	Name   string `json:"name"`
}

Folder represents a vault folder.

T type FoldersAPI

src 
type FoldersAPI interface {
	// List retrieves folders with optional search filter.
	List(ctx context.Context, search string) ([]Folder, error)

	// Get retrieves a single folder by its ID.
	Get(ctx context.Context, id string) (*Folder, error)

	// Create adds a new folder to the vault.
	Create(ctx context.Context, folder Folder) (*Folder, error)

	// Update modifies an existing folder.
	Update(ctx context.Context, id string, folder Folder) (*Folder, error)

	// Delete removes a folder from the vault.
	Delete(ctx context.Context, id string) error
}

FoldersAPI defines operations on folders for organizing vault items.

T type FoldersService

src 
type FoldersService struct {
	// contains filtered or unexported fields
}

FoldersService handles folder operations.

m func (*FoldersService) Create

src 
func (s *FoldersService) Create(ctx context.Context, folder Folder) (*Folder, error)

Create creates a new folder.

m func (*FoldersService) Delete

src 
func (s *FoldersService) Delete(ctx context.Context, id string) error

Delete deletes a folder.

m func (*FoldersService) Get

src 
func (s *FoldersService) Get(ctx context.Context, id string) (*Folder, error)

Get returns a single folder by ID.

m func (*FoldersService) List

src 
func (s *FoldersService) List(ctx context.Context, search string) ([]Folder, error)

List returns all folders, optionally filtered by search.

m func (*FoldersService) Update

src 
func (s *FoldersService) Update(ctx context.Context, id string, folder Folder) (*Folder, error)

Update updates an existing folder.

T type GenerateOptions

src 
type GenerateOptions struct {
	Lowercase     *bool   `json:"lowercase,omitempty"`
	Uppercase     *bool   `json:"uppercase,omitempty"`
	Number        *bool   `json:"number,omitempty"`
	Special       *bool   `json:"special,omitempty"`
	Length        *int    `json:"length,omitempty"`
	Passphrase    *bool   `json:"passphrase,omitempty"`
	Words         *int    `json:"words,omitempty"`
	Separator     *string `json:"separator,omitempty"`
	Capitalize    *bool   `json:"capitalize,omitempty"`
	IncludeNumber *bool   `json:"includeNumber,omitempty"`
}

GenerateOptions holds password/passphrase generation options.

T type GenerateResponse

src 
type GenerateResponse struct {
	Success bool `json:"success"`
	Data    struct {
		Object string `json:"object"`
		Data   string `json:"data"`
	} `json:"data"`
}

GenerateResponse wraps the /generate endpoint response.

T type Identity

src 
type Identity struct {
	Title          string `json:"title,omitempty"`
	FirstName      string `json:"firstName,omitempty"`
	MiddleName     string `json:"middleName,omitempty"`
	LastName       string `json:"lastName,omitempty"`
	Address1       string `json:"address1,omitempty"`
	Address2       string `json:"address2,omitempty"`
	Address3       string `json:"address3,omitempty"`
	City           string `json:"city,omitempty"`
	State          string `json:"state,omitempty"`
	PostalCode     string `json:"postalCode,omitempty"`
	Country        string `json:"country,omitempty"`
	Company        string `json:"company,omitempty"`
	Email          string `json:"email,omitempty"`
	Phone          string `json:"phone,omitempty"`
	SSN            string `json:"ssn,omitempty"`
	Username       string `json:"username,omitempty"`
	PassportNumber string `json:"passportNumber,omitempty"`
	LicenseNumber  string `json:"licenseNumber,omitempty"`
}

Identity represents identity-specific fields of a vault item.

T type Item

src 
type Item struct {
	Object          string            `json:"object,omitempty"`
	ID              string            `json:"id,omitempty"`
	OrganizationID  string            `json:"organizationId,omitempty"`
	FolderID        *string           `json:"folderId,omitempty"`
	Type            ItemType          `json:"type"`
	Reprompt        int               `json:"reprompt"`
	Name            string            `json:"name"`
	Notes           string            `json:"notes,omitempty"`
	Favorite        bool              `json:"favorite"`
	Login           *Login            `json:"login,omitempty"`
	Card            *Card             `json:"card,omitempty"`
	Identity        *Identity         `json:"identity,omitempty"`
	SecureNote      *SecureNote       `json:"secureNote,omitempty"`
	Fields          []Field           `json:"fields,omitempty"`
	PasswordHistory []PasswordHistory `json:"passwordHistory,omitempty"`
	Attachments     []Attachment      `json:"attachments,omitempty"`
	CollectionIDs   []string          `json:"collectionIds,omitempty"`
	RevisionDate    string            `json:"revisionDate,omitempty"`
	CreationDate    string            `json:"creationDate,omitempty"`
	DeletedDate     *string           `json:"deletedDate,omitempty"`
}

Item represents a vault item (cipher).

T type ItemType

src 
type ItemType int

ItemType represents the type of a vault item. 

const (
	ItemTypeLogin      ItemType = 1
	ItemTypeSecureNote ItemType = 2
	ItemTypeCard       ItemType = 3
	ItemTypeIdentity   ItemType = 4
	ItemTypeSSHKey     ItemType = 5
)

T type ItemsAPI

src 
type ItemsAPI interface {
	// List retrieves items from the vault with optional filtering.
	List(ctx context.Context, filter ListFilter) ([]Item, error)

	// Get retrieves a single item by its ID.
	Get(ctx context.Context, id string) (*Item, error)

	// Create adds a new item to the vault.
	Create(ctx context.Context, item Item) (*Item, error)

	// Update modifies an existing item.
	Update(ctx context.Context, id string, item Item) (*Item, error)

	// Delete removes an item (moves to trash).
	Delete(ctx context.Context, id string) error

	// Restore recovers a deleted item from the trash.
	Restore(ctx context.Context, id string) error

	// Move transfers an item to an organization with specified collections.
	Move(ctx context.Context, id, organizationID string, collectionIDs []string) error
}

ItemsAPI defines operations on vault items (ciphers). Items are the primary data type in a vault and can be logins, secure notes, cards, identities, or SSH keys.

T type ItemsService

src 
type ItemsService struct {
	// contains filtered or unexported fields
}

ItemsService handles vault item operations.

m func (*ItemsService) Create

src 
func (s *ItemsService) Create(ctx context.Context, item Item) (*Item, error)

Create creates a new vault item.

m func (*ItemsService) Delete

src 
func (s *ItemsService) Delete(ctx context.Context, id string) error

Delete deletes a vault item (soft delete).

m func (*ItemsService) Get

src 
func (s *ItemsService) Get(ctx context.Context, id string) (*Item, error)

Get returns a single vault item by ID.

m func (*ItemsService) List

src 
func (s *ItemsService) List(ctx context.Context, filter ListFilter) ([]Item, error)

List returns vault items matching the given filters.

m func (*ItemsService) Move

src 
func (s *ItemsService) Move(ctx context.Context, id, organizationID string, collectionIDs []string) error

Move moves a vault item to an organization with the given collection IDs.

m func (*ItemsService) Restore

src 
func (s *ItemsService) Restore(ctx context.Context, id string) error

Restore restores a soft-deleted vault item.

m func (*ItemsService) Update

src 
func (s *ItemsService) Update(ctx context.Context, id string, item Item) (*Item, error)

Update updates an existing vault item.

T type ListFilter

src 
type ListFilter struct {
	Search         string
	OrganizationID string
	CollectionID   string
	FolderID       string
	URL            string
	Trash          bool
}

ListFilter holds common filter parameters for list operations.

T type ListResponse

src 
type ListResponse[T any] struct {
	Success bool `json:"success"`
	Data    struct {
		Object string `json:"object"`
		Data   []T    `json:"data"`
	} `json:"data"`
}

ListResponse is a generic list response wrapper.

T type Login

src 
type Login struct {
	URIs     []LoginURI `json:"uris,omitempty"`
	Username string     `json:"username,omitempty"`
	Password string     `json:"password,omitempty"`
	TOTP     string     `json:"totp,omitempty"`
}

Login represents login-specific fields of a vault item.

T type LoginURI

src 
type LoginURI struct {
	Match *URIMatchType `json:"match,omitempty"`
	URI   string        `json:"uri"`
}

LoginURI represents a URI attached to a login item.

T type MessageResponse

src 
type MessageResponse struct {
	Success bool `json:"success"`
	Data    struct {
		Title   string `json:"title"`
		Message string `json:"message"`
		Raw     string `json:"raw"`
	} `json:"data"`
}

MessageResponse is a generic message response from the API.

T type MoveRequest

src 
type MoveRequest struct {
	CollectionIDs []string `json:"collectionIds"`
}

MoveRequest is the body for POST /move/:id/:organizationId.

T type NotFoundError

src 
type NotFoundError struct {
	Object string
	ID     string
}

NotFoundError is returned when the requested object is not found.

m func (*NotFoundError) Error

src 
func (e *NotFoundError) Error() string

T type NotificationHandler

src 
type NotificationHandler func(notifType NotificationType, payload NotificationPayload)

NotificationHandler is called when a server notification is received. It runs in a background goroutine — implementations must be safe for concurrent use.

T type NotificationPayload

src 
type NotificationPayload struct {
	ID             string
	UserID         string
	OrganizationID string
	CollectionIDs  []string
	RevisionDate   string
}

NotificationPayload contains details of a server notification.

T type NotificationType

src 
type NotificationType = api.NotificationType

NotificationType represents the type of server notification.

T type ObjectResponse

src 
type ObjectResponse[T any] struct {
	Success bool `json:"success"`
	Data    T    `json:"data"`
}

ObjectResponse is a generic single-object response wrapper.

T type OrgCollection

src 
type OrgCollection struct {
	Object         string   `json:"object,omitempty"`
	ID             string   `json:"id,omitempty"`
	OrganizationID string   `json:"organizationId,omitempty"`
	Name           string   `json:"name"`
	ExternalID     string   `json:"externalId,omitempty"`
	Groups         []string `json:"groups,omitempty"`
}

OrgCollection represents an organization collection with additional details.

T type OrgCollectionsAPI

src 
type OrgCollectionsAPI interface {
	// List retrieves collections in an organization with optional search.
	List(ctx context.Context, organizationID string, search string) ([]OrgCollection, error)

	// Get retrieves a single organization collection by its ID.
	Get(ctx context.Context, id string) (*OrgCollection, error)

	// Create adds a new collection to the organization.
	Create(ctx context.Context, collection OrgCollection) (*OrgCollection, error)

	// Update modifies an existing organization collection.
	Update(ctx context.Context, id string, collection OrgCollection) (*OrgCollection, error)

	// Delete removes a collection from the organization.
	Delete(ctx context.Context, id string) error
}

OrgCollectionsAPI defines operations on organization collections. Users with appropriate permissions can create, update, and delete org collections.

T type OrgCollectionsService

src 
type OrgCollectionsService struct {
	// contains filtered or unexported fields
}

OrgCollectionsService handles organization collection operations.

m func (*OrgCollectionsService) Create

src 
func (s *OrgCollectionsService) Create(ctx context.Context, collection OrgCollection) (*OrgCollection, error)

Create creates a new organization collection.

m func (*OrgCollectionsService) Delete

src 
func (s *OrgCollectionsService) Delete(ctx context.Context, id string) error

Delete deletes an organization collection.

m func (*OrgCollectionsService) Get

src 
func (s *OrgCollectionsService) Get(ctx context.Context, id string) (*OrgCollection, error)

Get returns a single organization collection by ID.

m func (*OrgCollectionsService) List

src 
func (s *OrgCollectionsService) List(ctx context.Context, organizationID string, search string) ([]OrgCollection, error)

List returns all organization collections. organizationID is required.

m func (*OrgCollectionsService) Update

src 
func (s *OrgCollectionsService) Update(ctx context.Context, id string, collection OrgCollection) (*OrgCollection, error)

Update updates an existing organization collection.

T type OrgMember

src 
type OrgMember struct {
	Object  string `json:"object,omitempty"`
	ID      string `json:"id,omitempty"`
	Name    string `json:"name"`
	Email   string `json:"email"`
	Status  int    `json:"status"`
	Type    int    `json:"type"`
	TwoStep bool   `json:"twoFactorEnabled"`
}

OrgMember represents an organization member.

T type OrgMembersAPI

src 
type OrgMembersAPI interface {
	// List retrieves all members in an organization.
	List(ctx context.Context, organizationID string) ([]OrgMember, error)

	// Confirm accepts a pending member into the organization.
	Confirm(ctx context.Context, id, organizationID string) error
}

OrgMembersAPI defines operations on organization members.

T type OrgMembersService

src 
type OrgMembersService struct {
	// contains filtered or unexported fields
}

OrgMembersService handles organization member operations.

m func (*OrgMembersService) Confirm

src 
func (s *OrgMembersService) Confirm(ctx context.Context, id, organizationID string) error

Confirm confirms an invited organization member.

m func (*OrgMembersService) List

src 
func (s *OrgMembersService) List(ctx context.Context, organizationID string) ([]OrgMember, error)

List returns all members of an organization.

T type Organization

src 
type Organization struct {
	Object  string `json:"object,omitempty"`
	ID      string `json:"id,omitempty"`
	Name    string `json:"name"`
	Status  int    `json:"status"`
	Type    int    `json:"type"`
	Enabled bool   `json:"enabled"`
}

Organization represents an organization.

T type OrganizationsAPI

src 
type OrganizationsAPI interface {
	// List retrieves organizations the user belongs to with optional search.
	List(ctx context.Context, search string) ([]Organization, error)

	// Get retrieves a single organization by its ID.
	Get(ctx context.Context, id string) (*Organization, error)
}

OrganizationsAPI defines read-only operations on organizations.

T type OrganizationsService

src 
type OrganizationsService struct {
	// contains filtered or unexported fields
}

OrganizationsService handles organization operations (read-only).

m func (*OrganizationsService) Get

src 
func (s *OrganizationsService) Get(ctx context.Context, id string) (*Organization, error)

Get returns a single organization by ID.

m func (*OrganizationsService) List

src 
func (s *OrganizationsService) List(ctx context.Context, search string) ([]Organization, error)

List returns all organizations, optionally filtered by search.

T type PasswordHistory

src 
type PasswordHistory struct {
	LastUsedDate string `json:"lastUsedDate"`
	Password     string `json:"password"`
}

PasswordHistory represents a password history entry.

T type SecureNote

src 
type SecureNote struct {
	Type int `json:"type"`
}

SecureNote represents secure note-specific fields.

T type Send

src 
type Send struct {
	Object         string    `json:"object,omitempty"`
	ID             string    `json:"id,omitempty"`
	AccessID       string    `json:"accessId,omitempty"`
	Type           SendType  `json:"type"`
	Name           string    `json:"name"`
	Notes          string    `json:"notes,omitempty"`
	File           *SendFile `json:"file,omitempty"`
	Text           *SendText `json:"text,omitempty"`
	Key            string    `json:"key,omitempty"`
	MaxAccessCount *int      `json:"maxAccessCount,omitempty"`
	AccessCount    int       `json:"accessCount,omitempty"`
	Password       string    `json:"password,omitempty"`
	Disabled       bool      `json:"disabled"`
	RevisionDate   string    `json:"revisionDate,omitempty"`
	DeletionDate   string    `json:"deletionDate"`
	ExpirationDate *string   `json:"expirationDate,omitempty"`
	HideEmail      bool      `json:"hideEmail"`
}

Send represents a Bitwarden Send object.

T type SendAPI

src 
type SendAPI interface {
	// List retrieves all Sends owned by the user.
	List(ctx context.Context) ([]Send, error)

	// Get retrieves a single Send by its ID.
	Get(ctx context.Context, id string) (*Send, error)

	// Create adds a new Send to the vault.
	Create(ctx context.Context, send Send) (*Send, error)

	// Update modifies an existing Send.
	Update(ctx context.Context, id string, send Send) (*Send, error)

	// Delete removes a Send from the vault.
	Delete(ctx context.Context, id string) error

	// RemovePassword removes the password protection from a Send.
	RemovePassword(ctx context.Context, id string) (*Send, error)
}

SendAPI defines operations on Bitwarden Send objects. Send allows secure sharing of data (text or files) with anyone, even non-Bitwarden users.

T type SendFile

src 
type SendFile struct {
	ID       string `json:"id,omitempty"`
	FileName string `json:"fileName"`
	Size     string `json:"size,omitempty"`
	SizeName string `json:"sizeName,omitempty"`
}

SendFile represents file details in a Send.

T type SendService

src 
type SendService struct {
	// contains filtered or unexported fields
}

SendService handles Bitwarden Send operations.

m func (*SendService) Create

src 
func (s *SendService) Create(ctx context.Context, send Send) (*Send, error)

Create creates a new Send.

m func (*SendService) Delete

src 
func (s *SendService) Delete(ctx context.Context, id string) error

Delete deletes a Send.

m func (*SendService) Get

src 
func (s *SendService) Get(ctx context.Context, id string) (*Send, error)

Get returns a single Send by ID.

m func (*SendService) List

src 
func (s *SendService) List(ctx context.Context) ([]Send, error)

List returns all Send items.

m func (*SendService) RemovePassword

src 
func (s *SendService) RemovePassword(ctx context.Context, id string) (*Send, error)

RemovePassword removes password protection from a Send.

m func (*SendService) Update

src 
func (s *SendService) Update(ctx context.Context, id string, send Send) (*Send, error)

Update updates an existing Send.

T type SendText

src 
type SendText struct {
	Text   string `json:"text"`
	Hidden bool   `json:"hidden"`
}

SendText represents text details in a Send.

T type SendType

src 
type SendType int

SendType represents the type of a Send. 

const (
	SendTypeText SendType = 0
	SendTypeFile SendType = 1
)

T type Status

src 
type Status struct {
	ServerURL string `json:"serverUrl"`
	LastSync  string `json:"lastSync"`
	UserEmail string `json:"userEmail"`
	UserID    string `json:"userId"`
	Status    string `json:"status"`
}

Status represents the response from /status.

T type StatusResponse

src 
type StatusResponse struct {
	Success bool            `json:"success"`
	Data    json.RawMessage `json:"data"`
}

StatusResponse wraps the status endpoint response.

T type SyncResponse

src 
type SyncResponse struct {
	Success bool `json:"success"`
	Data    struct {
		Title   string `json:"title"`
		Message string `json:"message"`
	} `json:"data"`
}

SyncResponse wraps the sync endpoint response.

T type TemplateType

src 
type TemplateType string

TemplateType represents the type of template to retrieve. 

const (
	TemplateItem           TemplateType = "item"
	TemplateItemField      TemplateType = "item.field"
	TemplateItemLogin      TemplateType = "item.login"
	TemplateItemCard       TemplateType = "item.card"
	TemplateItemIdentity   TemplateType = "item.identity"
	TemplateItemSecureNote TemplateType = "item.securenote"
	TemplateFolder         TemplateType = "folder"
	TemplateCollection     TemplateType = "collection"
	TemplateSend           TemplateType = "send"
	TemplateSendText       TemplateType = "send.text"
	TemplateSendFile       TemplateType = "send.file"
)

T type URIMatchType

src 
type URIMatchType int

URIMatchType represents the URI match detection type. 

const (
	URIMatchBaseDomain URIMatchType = 0
	URIMatchHost       URIMatchType = 1
	URIMatchStartsWith URIMatchType = 2
	URIMatchRegex      URIMatchType = 3
	URIMatchExact      URIMatchType = 4
	URIMatchNever      URIMatchType = 5
)

T type UnlockRequest

src 
type UnlockRequest struct {
	Password string `json:"password"`
}

UnlockRequest is the body for POST /unlock.

T type VaultClient

src 
type VaultClient interface {
	// Status returns the current vault status including lock state and user info.
	Status(ctx context.Context) (*Status, error)

	// Sync downloads the latest vault data from the server.
	Sync(ctx context.Context) error

	// Lock clears encryption keys and vault data from memory.
	Lock(ctx context.Context) error

	// Unlock authenticates and derives encryption keys from the password.
	Unlock(ctx context.Context, password string) error

	// Generate creates a password or passphrase based on the provided options.
	Generate(ctx context.Context, opts GenerateOptions) (string, error)

	// Items returns the vault items (ciphers) API.
	Items() ItemsAPI

	// Folders returns the folders API.
	Folders() FoldersAPI

	// Collections returns the user collections API.
	Collections() CollectionsAPI

	// OrgCollections returns the organization collections API.
	OrgCollections() OrgCollectionsAPI

	// Organizations returns the organizations API.
	Organizations() OrganizationsAPI

	// OrgMembers returns the organization members API.
	OrgMembers() OrgMembersAPI

	// Send returns the Bitwarden Send API.
	Send() SendAPI

	// Attachments returns the file attachments API.
	Attachments() AttachmentsAPI
}

VaultClient defines the unified interface for interacting with a Bitwarden vault. Both Client (CLI-based via bw serve) and DirectClient (direct server communication) implement this interface, allowing applications to work with either mode seamlessly.

The interface provides methods for vault lifecycle management (Status, Sync, Lock, Unlock), password generation, and access to various vault services through sub-APIs.

T type VaultLockedError

src 
type VaultLockedError struct{}

VaultLockedError is returned when the vault is locked.

m func (*VaultLockedError) Error

src 
func (e *VaultLockedError) Error() string

Directories

PathSynopsis
crypto
example
internal/api

Source Files