go.bigb.es/go-bitwarden

v1.0.0
Doc Versions Source

Index

Types

T type AuthClient

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

AuthClient handles authentication against the Bitwarden/Vaultwarden identity API.

f func NewAuthClient

src 
func NewAuthClient(transport *Transport, device DeviceInfo, identityURL string) *AuthClient

NewAuthClient creates a new authentication client.

m func (*AuthClient) GetAPIKey

src 
func (a *AuthClient) GetAPIKey(ctx context.Context, email, password string) (clientID, clientSecret string, err error)

GetAPIKey retrieves (or creates) an API key for the current user. Requires an authenticated session (access token set on transport).

m func (*AuthClient) Login

src 
func (a *AuthClient) Login(ctx context.Context, email, password string) (*TokenResponse, *crypto.KeyChain, error)

Login authenticates with email and master password, returning the token response. It also sets up the transport with the received tokens and configures token refresh.

m func (*AuthClient) LoginWithAPIKey

src 
func (a *AuthClient) LoginWithAPIKey(ctx context.Context, clientID, clientSecret, email, password string) (*TokenResponse, *crypto.KeyChain, error)

LoginWithAPIKey authenticates using an API key (client_credentials grant). API keys bypass 2FA but do NOT return encryption keys — the master password is still required to derive the KeyChain for vault operations.

m func (*AuthClient) Prelogin

src 
func (a *AuthClient) Prelogin(ctx context.Context, email string) (*PreloginResponse, error)

Prelogin retrieves KDF parameters for the given email.

m func (*AuthClient) RefreshToken

src 
func (a *AuthClient) RefreshToken(ctx context.Context) error

RefreshToken refreshes the access token using the stored refresh token.

m func (*AuthClient) Register

src 
func (a *AuthClient) Register(ctx context.Context, email, password, name string, cfg crypto.DeriveKeyConfig) error

Register creates a new account on the server.

m func (*AuthClient) SetTwoFactorProvider

src 
func (a *AuthClient) SetTwoFactorProvider(p TwoFactorProvider)

SetTwoFactorProvider sets the 2FA callback.

T type DeviceInfo

src 
type DeviceInfo struct {
	Name       string
	Identifier string
	Type       int // 14 = CLI/SDK
}

DeviceInfo describes the client device for token requests.

f func DefaultDeviceInfo

src 
func DefaultDeviceInfo() DeviceInfo

DefaultDeviceInfo returns sensible defaults for a Go SDK client.

T type ErrorModel

src 
type ErrorModel struct {
	Message string `json:"message"`
	Object  string `json:"object"`
}

ErrorModel is the nested error object in server error responses.

T type ErrorResponse

src 
type ErrorResponse struct {
	Message          string              `json:"message"`
	Error            string              `json:"error"`
	ErrorDescription string              `json:"error_description"`
	ValidationErrors map[string][]string `json:"validationErrors,omitempty"`
	ErrorModel       *ErrorModel         `json:"errorModel,omitempty"`
}

ErrorResponse is the error format returned by the server API.

T type NotificationHandler

src 
type NotificationHandler func(msg NotificationMessage)

NotificationHandler is called when a notification is received.

T type NotificationMessage

src 
type NotificationMessage struct {
	Type      NotificationType
	ContextID string
	Payload   NotificationPayload
}

NotificationMessage is the decoded notification from the server.

T type NotificationPayload

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

NotificationPayload holds the payload fields of a notification.

T type NotificationsClient

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

NotificationsClient manages a WebSocket connection to the notifications hub.

f func NewNotificationsClient

src 
func NewNotificationsClient(transport *Transport, handler NotificationHandler) *NotificationsClient

NewNotificationsClient creates a new notifications client.

m func (*NotificationsClient) Close

src 
func (nc *NotificationsClient) Close() error

Close stops the WebSocket connection and waits for the background goroutine to exit.

m func (*NotificationsClient) Connect

src 
func (nc *NotificationsClient) Connect(ctx context.Context) error

Connect starts the background WebSocket connection with automatic reconnection. The provided context controls the lifetime of the connection — cancel it to stop.

m func (*NotificationsClient) SetLogger

src 
func (nc *NotificationsClient) SetLogger(l *log.Logger)

SetLogger sets a logger for debug output. By default, logging is disabled.

T type PreloginRequest

src 
type PreloginRequest struct {
	Email string `json:"email"`
}

PreloginRequest is the body for POST /identity/accounts/prelogin.

T type PreloginResponse

src 
type PreloginResponse struct {
	Kdf            int `json:"kdf"`
	KdfIterations  int `json:"kdfIterations"`
	KdfMemory      int `json:"kdfMemory,omitempty"`
	KdfParallelism int `json:"kdfParallelism,omitempty"`
}

PreloginResponse contains KDF parameters for a given email.

T type RegisterKeys

src 
type RegisterKeys struct {
	PublicKey           string `json:"publicKey"`
	EncryptedPrivateKey string `json:"encryptedPrivateKey"`
}

RegisterKeys contains the public/private key pair for registration.

T type RegisterRequest

src 
type RegisterRequest struct {
	Name               string       `json:"name"`
	Email              string       `json:"email"`
	MasterPasswordHash string       `json:"masterPasswordHash"`
	MasterPasswordHint *string      `json:"masterPasswordHint"`
	Key                string       `json:"key"`
	Kdf                int          `json:"kdf"`
	KdfIterations      int          `json:"kdfIterations"`
	KdfMemory          int          `json:"kdfMemory,omitempty"`
	KdfParallelism     int          `json:"kdfParallelism,omitempty"`
	Keys               RegisterKeys `json:"keys"`
}

RegisterRequest is the body for POST /identity/accounts/register.

T type ServerError

src 
type ServerError struct {
	StatusCode int
	Msg        string
	Raw        string
}

ServerError represents an error response from the Bitwarden/Vaultwarden server.

m func (*ServerError) Error

src 
func (e *ServerError) Error() string

T type SyncOrg

src 
type SyncOrg struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Key     string `json:"key"`
	Status  int    `json:"status"`
	Type    int    `json:"type"`
	Enabled bool   `json:"enabled"`
}

SyncOrg is an organization entry in the sync profile.

T type SyncProfile

src 
type SyncProfile struct {
	ID            string    `json:"id"`
	Email         string    `json:"email"`
	Name          string    `json:"name"`
	Organizations []SyncOrg `json:"organizations"`
}

SyncProfile is the profile section of the sync response.

T type SyncResponse

src 
type SyncResponse struct {
	Profile     SyncProfile       `json:"profile"`
	Folders     []json.RawMessage `json:"folders"`
	Ciphers     []json.RawMessage `json:"ciphers"`
	Collections []json.RawMessage `json:"collections"`
	Sends       []json.RawMessage `json:"sends"`
}

SyncResponse is the response from GET /api/sync.

T type TokenResponse

src 
type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresIn    int    `json:"expires_in"`
	TokenType    string `json:"token_type"`

	// Encryption keys — only present on password grant (not refresh).
	Key        string `json:"Key"`
	PrivateKey string `json:"PrivateKey"`

	// 2FA challenge fields — present when HTTP 400 + 2FA required.
	TwoFactorProviders2 map[string]map[string]any `json:"TwoFactorProviders2,omitempty"`
}

TokenResponse is the response from POST /identity/connect/token.

T type Transport

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

Transport provides authenticated HTTP access to the Bitwarden/Vaultwarden server API.

f func NewTransport

src 
func NewTransport(baseURL string, httpClient *http.Client) *Transport

NewTransport creates a new authenticated transport.

m func (*Transport) AccessToken

src 
func (t *Transport) AccessToken(ctx context.Context) (string, error)

AccessToken returns the current access token, refreshing if expired.

m func (*Transport) BaseURL

src 
func (t *Transport) BaseURL() string

BaseURL returns the configured base URL.

m func (*Transport) ClearTokens

src 
func (t *Transport) ClearTokens()

ClearTokens removes all stored tokens.

m func (*Transport) Delete

src 
func (t *Transport) Delete(ctx context.Context, path string) ([]byte, error)

Delete performs an authenticated DELETE request.

m func (*Transport) Get

src 
func (t *Transport) Get(ctx context.Context, path string, query url.Values) ([]byte, error)

Get performs an authenticated GET request.

m func (*Transport) Post

src 
func (t *Transport) Post(ctx context.Context, path string, body any) ([]byte, error)

Post performs an authenticated POST request with a JSON body.

m func (*Transport) PostForm

src 
func (t *Transport) PostForm(ctx context.Context, fullURL string, form url.Values) ([]byte, error)

PostForm performs an authenticated POST request with form-encoded body. Used for the token endpoint.

m func (*Transport) PostFormNoAuth

src 
func (t *Transport) PostFormNoAuth(ctx context.Context, fullURL string, form url.Values) ([]byte, error)

PostFormNoAuth performs an unauthenticated POST with form-encoded body.

m func (*Transport) PostNoAuth

src 
func (t *Transport) PostNoAuth(ctx context.Context, path string, body any) ([]byte, error)

PostNoAuth performs an unauthenticated POST request with a JSON body.

m func (*Transport) Put

src 
func (t *Transport) Put(ctx context.Context, path string, body any) ([]byte, error)

Put performs an authenticated PUT request with a JSON body.

m func (*Transport) SetRefreshFunc

src 
func (t *Transport) SetRefreshFunc(fn func(ctx context.Context, refreshToken string) (*TokenResponse, error))

SetRefreshFunc sets the callback used to refresh expired tokens.

m func (*Transport) SetTokens

src 
func (t *Transport) SetTokens(accessToken, refreshToken string, expiresIn int)

SetTokens stores the access and refresh tokens from a login response.

T type TwoFactorProvider

src 
type TwoFactorProvider interface {
	// ProvideTwoFactor is called with the available 2FA provider types and their params.
	// It should return the chosen provider type, the token/code, and whether to remember.
	ProvideTwoFactor(ctx context.Context, providers map[string]map[string]any) (providerType int, token string, remember bool, err error)
}

TwoFactorProvider is called when the server requires 2FA during login.

Source Files