vibr8vault-sdk

Python SDK for Vibr8Vault — a self-hosted secrets manager.

Installation

pip install vibr8vault-sdk

Development Setup

# Clone the repo and navigate to the Python SDK
cd sdk/python

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the SDK in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy src/

Quick Start

from vibr8vault import Vibr8Vault

vault = Vibr8Vault(address="http://localhost:8200", token="your-service-token")

# Write a secret
vault.secrets.write("apps/backend/prod", {
    "DB_PASSWORD": "s3cret",
    "API_KEY": "ak_live_xyz",
})

# Read it back
secret = vault.secrets.read("apps/backend/prod")
print(secret["data"]["DB_PASSWORD"])  # → s3cret

# List secrets under a prefix
listing = vault.secrets.list("apps/")
print(listing["keys"])

# Check vault health
health = vault.sys.health()
print(health["status"])

API Reference

Secrets

vault.secrets.read(path, version=None)        # Read a secret (optionally a specific version)
vault.secrets.write(path, data)                # Write key-value pairs to a path
vault.secrets.delete(path, hard=False)         # Soft-delete (or hard-delete) a secret
vault.secrets.list(prefix)                     # List secret paths under a prefix
vault.secrets.versions(path)                   # List all versions of a secret

Namespace-scoped variants: read_ns, write_ns, delete_ns, list_ns, versions_ns — each takes ns as the first argument.

Tokens

vault.tokens.create(type=None, ttl=None, policies=None, max_uses=None)
vault.tokens.revoke(id)
vault.tokens.list()

Auth

vault.auth.login(username, password)
vault.auth.me()

Users

vault.users.create(username, password, policies=None)
vault.users.list()
vault.users.get(id)
vault.users.update(id, password=None, policies=None)
vault.users.delete(id)

System

vault.sys.health()
vault.sys.status()
vault.sys.unseal(key)
vault.sys.seal()

Namespaces

vault.namespaces.list()
vault.namespaces.get(name)
vault.namespaces.create(name)
vault.namespaces.delete(name)

Policies

vault.policies.list(ns=None)
vault.policies.get(name, ns=None)
vault.policies.create(yaml, ns=None)
vault.policies.delete(name, ns=None)

Client Management

vault.set_token(token)    # Change the auth token after construction
vault.close()             # Close the underlying HTTP connection

Use as a context manager for automatic cleanup:

with Vibr8Vault("http://localhost:8200", "your-token") as vault:
    secret = vault.secrets.read("apps/backend/prod")

Error Handling

from vibr8vault import Vibr8Vault, Vibr8VaultError

vault = Vibr8Vault("http://localhost:8200", "your-token")

try:
    secret = vault.secrets.read("nonexistent/path")
except Vibr8VaultError as e:
    print(f"Error: {e} (HTTP {e.status})")

Requirements

• Python 3.9+
• A running Vibr8Vault instance