Clients & Libraries

Everything in the secretserver-clients repository: four language libraries, an Ansible lookup, a desktop app, an MCP bridge, agent skills and the offline cache design.

Choose a client

Go

library

Typed services for secrets, certificates, keys and more, plus Call() for any REST route.

Python

library

Standard library only, Python 3.8+. Reads SS_API_KEY and SS_API_URL from the environment.

Node.js / TypeScript

library

Zero dependencies, native fetch, Node.js 18+. Ships TypeScript types.

PHP

library

PHP 8.0+ with the curl and json extensions. No Composer dependencies.

Ansible

lookup

A lookup plugin that reads secrets and resolves %%NAME%% templates inside playbooks.

Desktop app

GUI

A Fyne desktop client for browsing, creating and editing secrets and variables.

MCP bridge

stdio

Operation-only signing with non-exportable HSM and smart-card keys for MCP clients.

Agent skills

skills

Skill packages that teach coding agents the safe way to use SecretServer.

aikeys

local CLI

A separate command line tool that keeps API keys in an encrypted local vault or keychain and renders .env files for coding agents.

Offline cache service

design

A reviewed design for an encrypted, time-bounded offline lease cache. Not yet a running daemon.

Getting the source

All clients live in one public, MIT-licensed repository. The libraries are not published to PyPI, npm or Packagist, so the guides install them from the repository. The secretserver name on PyPI belongs to an unrelated package; do not pip install secretserver.

git clone https://github.com/afterdarksys/secretserver-clients.git
cd secretserver-clients

Client	Directory	Build or install from source
Python	`python/`	`pip install ./python`
Python, without a clone	`python/`	`pip install "git+https://github.com/afterdarksys/secretserver-clients.git#subdirectory=python"`
Node.js / TypeScript	`node/`	`cd node && npm install && npm run build`
PHP	`php/`	Composer path repository (see the PHP guide)
Go	`go/`	`go get github.com/afterdarksys/secretserver-clients/go@latest`
Ansible	`ansible/`	Copy secretserver.py into lookup_plugins/
Desktop app	`go-gui/`	go build . (cgo and graphics libraries; see the guide)
MCP bridge	`mcp/`	`go build -o secretserver-mcp .`
Agent skills	`skills/`	Copy the skill folder

The repository also has helper scripts: scripts/install-python.sh, scripts/install-node.sh, scripts/install-php.sh and scripts/install-go.sh. Each guide shows the exact commands those scripts run.

Authentication

Clients authenticate with an API key sent as Authorization: Bearer <key>. An account admin creates keys through POST /api/v1/api-keys (the admin:* scope). Each key carries permission scopes; grant only what the application needs. The key is shown once.

Client	API key	Base URL	Default URL
Python	`api_key=`	`api_url=`	https://api.secretserver.io
Node.js	`apiKey`	`apiUrl`	https://api.secretserver.io
PHP	`$apiKey`	`$apiUrl`	https://api.secretserver.io
Ansible	`api_key`	`api_url`	https://api.secretserver.io
Go	`Config.APIKey`	`Config.APIURL`	https://api.secretserver.io

Python, Node.js, PHP and Ansible fall back to SS_API_KEY and SS_API_URL when the argument is not passed. The Go library does not read the environment; pass the values in Config. Base URLs work with or without the /api/v1 suffix.

export SS_API_KEY=sk_...
export SS_API_URL=https://api.secretserver.io   # optional

Full option lists, including timeouts, private CA files and the partial update switch, are in the client configuration guide.

Shared behavior

Behavior	Detail
Transport	https only. Plain http is accepted only for localhost, 127.0.0.1 or ::1. URLs with embedded credentials are rejected. TLS verification cannot be turned off.
Redirects	Never followed, so the bearer key cannot be replayed to another origin.
Response limits	JSON responses are capped at 4 MiB and raw downloads at 16 MiB.
Errors	HTTP failures expose the status code but never echo the server response body. 401, 403, 404 and 409 map to typed errors.
Retries	Mutations are not retried automatically. After a timeout, read the current state before trying again.
Escape hatch	Every library can call any REST route under /api/v1 before a typed helper exists.
Partial updates	Secret updates send only the fields you pass. They are refused unless you opt in or pass an ETag from a previous read, because servers older than build 3075630 treat PUT as a full replace.

Secret paths and versions

Library read helpers accept three shapes:

Shape	Example	REST route
Name	`db-password`	`GET /api/v1/secrets/db-password`
Container and key	`production/db-password`	`GET /api/v1/s/production/db-password`
Container, key and version	`production/db-password/2`	`GET /api/v1/s/production/db-password/2`

Versions run from 1 (current) to 12; 2 is the previous value. A read by name returns the record with its values under data. A container path read returns {meta, data}.

Secret names are immutable, and request bodies carry the value under data, for example {"name":"db-password","data":{"value":"..."}}.

Permission scopes

These are the scopes the API checks. The admin:* scope grants everything.

Scope	Grants
`secrets:read / write / delete`	Generic secrets
`credentials:read / write / delete`	Extended credential types
`credentials:use`	Use provider credentials without exporting them
`containers:read / write`	Container namespaces
`certs:read / write / revoke`	TLS certificates
`ssh:read / write`	SSH keys
`gpg:read / write`	GPG keys
`passwords:read / write`	Passwords
`tokens:read / write`	Third-party API tokens
`variables:read / write`	Named %%NAME%% variable assignments
`keys:sign / keys:decrypt`	Operation-only use of non-exportable keys
`history:read`	Version history
`sharing:manage`	Shares
`temp-access:create`	Time-limited access tokens
`export:read`	Export key material and certificates
`transform:use`	Encode, decode and detect formats
`intelligence:read`	Breach detection
`extract:run`	Secret discovery
`ldap:use`	LDAP import and export
`saml:read / write`	SAML federation
`oidc:read / write`	OIDC clients
`audit:read`	Audit logs
`settings:write`	Account settings
`webhooks:manage`	Webhooks
`admin:*`	All permissions

Client configuration →API Reference →Clients overview →Source on GitHub →