SDKs
The fastest way to integrate with Sirr is through one of the official client libraries. Each SDK wraps the HTTP API so you can push and retrieve secrets with a single function call.
Official libraries
Node.js
The @sirrlock/node package is a zero-dependency TypeScript client built on native fetch. It ships ESM and CJS bundles so it works in Node.js, Deno, Bun, and edge runtimes.
Install
npm install @sirrlock/node
Usage
import { SirrClient } from '@sirrlock/node'
const sirr = new SirrClient({
server: process.env.SIRR_SERVER,
token: process.env.SIRR_TOKEN,
})
// Push a secret with a 1-hour TTL and 3 read limit
await sirr.push('db/password', 's3cret!', {
ttl: 3600,
reads: 3,
})
// Retrieve the secret
const secret = await sirr.get('db/password')
console.log(secret.value) // "s3cret!"
Python
The sirr package provides both synchronous and asynchronous clients powered by httpx. Python 3.10+ is supported.
Install
pip install sirr
Sync usage
import os
from sirr import SirrClient
client = SirrClient(
server=os.environ["SIRR_SERVER"],
token=os.environ["SIRR_TOKEN"],
)
# Push a secret with a 1-hour TTL and 3 read limit
client.push("db/password", "s3cret!", ttl=3600, reads=3)
# Retrieve the secret — returns the value string, or None if burned/expired
value = client.get("db/password")
print(value) # "s3cret!"
Async usage
from sirr import AsyncSirrClient
async with AsyncSirrClient(
server=os.environ["SIRR_SERVER"],
token=os.environ["SIRR_TOKEN"],
) as client:
await client.push("db/password", "s3cret!", ttl=3600, reads=3)
value = await client.get("db/password")
.NET
Sirr.Client is an async-first .NET library built on HttpClient. Targets .NET 8+ and supports dependency injection via IHttpClientFactory.
Install
dotnet add package Sirr.Client
Usage
using Sirr;
var client = new SirrClient(new SirrOptions
{
Server = Environment.GetEnvironmentVariable("SIRR_SERVER"),
Token = Environment.GetEnvironmentVariable("SIRR_TOKEN"),
});
// Push a secret
await client.PushAsync("db/password", "s3cret!", new PushOptions
{
Ttl = 3600,
Reads = 3,
});
// Retrieve the secret
var secret = await client.GetAsync("db/password");
Console.WriteLine(secret.Value); // "s3cret!"
Rust CLI
The sirr binary is both the server and a built-in CLI. You can use it to push and retrieve secrets directly from the command line without any additional tooling.
Install via Cargo
cargo install sirr
Or download a prebuilt binary from the GitHub releases page.
CLI usage
# Set your server and token
export SIRR_SERVER=http://localhost:39999
export SIRR_TOKEN=your-master-key
# Push a secret with a 1-hour TTL
sirr push db/password "s3cret!" --ttl 3600 --reads 3
# Get a secret
sirr get db/password
# List all secrets (metadata only)
sirr list
# Delete a secret
sirr delete db/password
Multi-tenant (org-scoped)
All three SDKs support multi-tenant mode. Pass an org parameter to scope secrets, principals, and keys to a specific organization. The examples above use public bucket mode (no org). The examples below show org-scoped mode.
Org-scoped mode requires a principal key (not the master key). Start the server with sirrd serve --init to bootstrap a default org and admin principal with temporary keys.
Constructor with org
import { SirrClient } from '@sirrlock/node'
const sirr = new SirrClient({
server: process.env.SIRR_SERVER,
token: process.env.SIRR_TOKEN,
org: process.env.SIRR_ORG, // org ID from auto-init or createOrg
})
Org-scoped push and get
// Push to org bucket
await sirr.push('db/password', 's3cret!', { ttl: 3600, reads: 3 })
// Retrieve from org bucket
const secret = await sirr.get('db/password')
console.log(secret.value) // "s3cret!"
/me endpoint
// Get the current principal's identity and permissions
const me = await sirr.me()
console.log(me.principal_id) // "admin"
console.log(me.org_id) // "default"
console.log(me.permissions) // ["read", "write", "admin", ...]
Admin methods
// Create a new organization (requires master key)
const org = await sirr.orgs.create({ name: 'acme-corp' })
// Create a principal in the org
const principal = await sirr.principals.create({
org: org.id,
name: 'deploy-bot',
role: 'writer',
})
// Create a key for the principal
const key = await sirr.principals.createKey({
org: org.id,
principal: principal.id,
name: 'ci-key',
})
console.log(key.token) // Save — shown only once
Audit, webhooks & keys
All three SDKs expose methods for the newer Sirr server features: audit logs, webhooks, and scoped API keys.
Audit logs
// Query audit log
const logs = await sirr.audit({ action: 'secret.read', limit: 50 })
// Query with time range
const recent = await sirr.audit({ since: Math.floor(Date.now() / 1000) - 86400 })
Webhooks
// Register a webhook
const wh = await sirr.webhooks.create({
url: 'https://example.com/hooks/sirr',
events: ['secret.created', 'secret.burned'],
})
// List and delete
const all = await sirr.webhooks.list()
await sirr.webhooks.delete(wh.id)
Scoped API keys
// Create a scoped key
const key = await sirr.keys.create({
name: 'CI pipeline',
permissions: ['read', 'write'],
prefix: 'ci/',
})
console.log(key.token) // Save — shown only once
// List and revoke
const keys = await sirr.keys.list()
await sirr.keys.delete(key.id)