Bitwarden Secrets Manager SDK

The SDK is a monorepo structured with cargo workspaces. Key components include:

• bitwarden: The core Rust API for interacting with the secrets manager.
• bitwarden-c: C bindings for FFI interop.
• bitwarden-json: A JSON wrapper around the bitwarden crate that powers other language bindings.
• bitwarden-napi: Node-API bindings for Node.js environments.
• bws: The Command Line Interface (CLI) for interacting with the Bitwarden Secrets Manager.
• sdk-schemas: A generator for JSON schemas used by the bindings.

The SDK is designed around a json based API to minimize the effort required to support new languages.

The Pattern:

1. Every language binding only needs to implement a single method: run_command.
2. JSON schemas are generated from the Rust structs in the bitwarden crate using schemars.
3. These schemas are then used by QuickType to generate the specific API bindings for each target language.

npm run schemas

The Bitwarden Go SDK utilizes FFI calls to the Bitwarden Rust SDK via cgo. It supports the following statically linked targets:

• Linux: x86-64 & arm64
• macOS: x86-64 & arm64
• Windows: x86-64

Because the fake server requires valid cryptography keys (derived from the fake access token), you should use a legitimate Secrets Manager client (like the bws CLI) to generate valid ciphers.

When you run a command like bws secret create against the fake server, the server logs will display the generated ciphers. These ciphers can then be embedded directly into the fake server for testing purposes.

RUST_LOG=info cargo run --quiet --bin fake-server

# in another shell session, create a secret
bws secret create 'my new key' 'my new value' --note 'optional note' "$(uuidgen)"

To use the Bitwarden Go SDK on Windows, you need Go and the mingw-w64 GCC compiler.

1. Install Prerequisites: Install the mingw-w64 toolchain (recommended via the Visual Studio Code guide).
2. Configure Environment: Enable cgo and set the C and C++ compilers to gcc and g++.
3. Add Module: Use go get to fetch the SDK.
4. Build: Use standard go build.

# Configure Go environment
go env -w CGO_ENABLED=1
go env -w CC=gcc CXX=g++

# Add the module
go get github.com/bitwarden/sdk-go/v2

# Build
go build

When using an IDE like CLion, you may need to manually set the TARGET CMake variable in your IDE's CMake options settings to point to the bitwarden_c library.

# Example for macOS
-DTARGET=../../target/release/libbitwarden_c.dylib

Use the provided build.sh script to compile the WebAssembly module. You can choose between a development build or a release build using the -r flag.

# dev build
./build.sh

# release build
./build.sh -r

If you need to build the SDK locally, ensure you have the following requirements installed:

• Python 3
• Rust
• maturin (Install via pip install maturin, or pip install maturin[patchelf] on Linux)
• npm
• uv (recommended for test automation)

Build Steps

1. Install dependencies and generate schemas:

npm install
npm run schemas # generate schemas.py

2. Navigate to the Python directory:

cd languages/python/

3. Create and activate a virtual environment:

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

Windows:

python -m venv venv

# For cmd.exe:
venv\Scripts\activate.bat

# For PowerShell:
venv\Scripts\Activate.ps1

4. Build and run the development installation:

maturin develop
python3 ./example.py

5. Close the virtual environment:

deactivate

To interact with the Bitwarden Secrets Manager, you must first create a BitwardenClient using BitwardenSettings. You then authenticate using an access token via the auth().loginAccessToken() method. You can optionally provide a stateFile path (e.g., from an environment variable) to manage session state.

import com.bitwarden.sdk.*;
import com.bitwarden.sdk.schema.*;

import java.lang.System;
import java.util.UUID;
import java.time.OffsetDateTime;

String stateFile = System.getenv("STATE_FILE");

BitwardenSettings bitwardenSettings = new BitwardenSettings();
bitwardenSettings.setApiUrl("https://api.bitwarden.com");
bitwardenSettings.setIdentityUrl("https://identity.bitwarden.com");
BitwardenClient bitwardenClient = new BitwardenClient(bitwardenSettings);
bitwardenClient.auth().loginAccessToken("<access-token>", stateFile);

The Bitwarden Java client library is built using Gradle. The resulting BitwardenSDK.jar file is located in the build/libs directory after a successful build.

Prerequisites

• JDK 17 must be installed.
• The Bitwarden SDK native library must be built (refer to the main SDK README for native build instructions).

./gradlew build