Developer Libraries

Getting an API Key

API keys are created in the SecretServer dashboard. Each key carries permission scopes — grant only the scopes your application needs.

1. Log in and go to Settings → API Keys
2. Click New API Key
3. Give the key a name (e.g. prod-app) and select the required scopes
4. Copy the key — it is shown only once

# Set in your shell
export SS_API_KEY=sk_live_...

# Or pass at runtime
SS_API_KEY=sk_live_... my-app

All libraries read SS_API_KEY from the environment automatically, so you only need to pass it explicitly when overriding per-request.

🐍 Python

Zero external dependencies — built on the Python standard library. Supports Python 3.8+.

pip install secretserver

Quick start

from secretserver import SecretServerClient

ss = SecretServerClient(api_key="sk_live_...")
# or: set SS_API_KEY in the environment and call SecretServerClient()

# Retrieve a secret by path  (container/key  or  container/key/version)
db_password = ss.secret("production/postgres-password")

# Get the previous version (2 = one back, 3 = two back...)
old_password = ss.secret("production/postgres-password/2")

Working with secrets

# Full secret object including metadata
secret = ss.get_secret("uuid-of-secret")

# List all secrets
secrets = ss.list_secrets()

# Create a secret
ss.create_secret("backup-key", "s3cur3_v@lue", tags={"env": "prod"})

Extended credential types

# Computer credentials
comps = ss.credentials("computer-credentials")
servers = comps.list()
comps.create({
    "name": "web-server-01",
    "hostname": "web01.internal",
    "ip_address": "10.0.0.10",
    "os_type": "linux",
    "admin_user": "admin",
    "password": "secure-password",
})

# WiFi credentials
wifi = ss.credentials("wifi-credentials")
wifi.create({
    "name": "Office WiFi",
    "ssid": "Corp-Network",
    "security_protocol": "WPA3",
    "password": "wifi-password",
})

Sharing & temp access

# Share a secret with a colleague (read-only, expires in 24 h)
ss.share("computer-credentials", secret["id"],
         "colleague@example.com", expires_hours=24)

# Generate a time-limited access token (valid 15 minutes)
grant = ss.create_temp_access("computer-credentials", secret["id"],
                               duration_seconds=900)
print(grant["token"])    # share this token — it works without an API key
print(grant["expires_at"])

Version history

# List version metadata
versions = ss.get_history("computer-credentials", secret["id"])

# Retrieve a specific historical value
old = ss.get_version("computer-credentials", secret["id"], version=2)

🟩 Node.js / TypeScript

Native fetch — no external dependencies. Full TypeScript types included. Supports Node.js 18+ and all modern bundlers.

npm install secretserver

Quick start

import { SecretServerClient } from "secretserver";

const ss = new SecretServerClient({ apiKey: process.env.SS_API_KEY });

// Path-based lookup
const dbPassword = await ss.secret("production/postgres-password");

// Previous version
const prev = await ss.secret("production/postgres-password/2");

Certificates & SSH keys

// List TLS certificates
const certs = await ss.listCertificates();

// Enroll a new certificate
const cert = await ss.enrollCertificate("wildcard-prod", "*.example.com", ["example.com"], true);

// Generate an SSH key
const key = await ss.generateSSHKey("deploy-key", "ed25519");
console.log(key.public_key);

Extended credential types

// Computer credentials
const servers = await ss.computerCredentials.list();
await ss.computerCredentials.create({
  name: "web-server-01",
  hostname: "web01.internal",
  ip_address: "10.0.0.10",
  os_type: "linux",
  admin_user: "admin",
  password: "secure-password",
});

// All credential types follow the same pattern:
// ss.wifiCredentials.list() / .get(id) / .create(data) / .update(id, data) / .delete(id)
// ss.windowsCredentials, ss.socialCredentials, ss.diskCredentials,
// ss.serviceConfig, ss.rootCredentials, ss.ldapBindCredentials,
// ss.integrationCredentials, ss.codeSigningKeys

Sharing & temp access

// Share with a colleague
await ss.share("computer-credentials", secretId, "bob@example.com", "read", "2026-03-01T00:00:00Z");

// Temp access token (15 minutes)
const grant = await ss.createTempAccess("computer-credentials", secretId, 900);
console.log(grant.token);     // works without an API key until expires_at
console.log(grant.expires_at);

Version history

const versions = await ss.getHistory("computer-credentials", secretId);
const oldValue  = await ss.getVersion("computer-credentials", secretId, 2);

🐘 PHP

Requires PHP 8.0+ with the curl extension.

composer require afterdark/secretserver

Quick start

<?php
use SecretServer\SecretServerClient;

$ss = new SecretServerClient(getenv('SS_API_KEY'));

// Path-based lookup
$dbPassword = $ss->secret('production/postgres-password');

// Previous version
$prev = $ss->secret('production/postgres-password/2');

Extended credential types

// Computer credentials
$comps = $ss->credentials('computer-credentials');
$servers = $comps->list();
$comps->create([
    'name'       => 'web-server-01',
    'hostname'   => 'web01.internal',
    'ip_address' => '10.0.0.10',
    'os_type'    => 'linux',
    'admin_user' => 'admin',
    'password'   => 'secure-password',
]);

// WiFi credentials
$wifi = $ss->credentials('wifi-credentials');
$wifi->create([
    'name'              => 'Office WiFi',
    'ssid'              => 'Corp-Network',
    'security_protocol' => 'WPA3',
    'password'          => 'wifi-password',
]);

// Certificates
$cert = $ss->enrollCertificate('wildcard-prod', '*.example.com', ['example.com'], true);

Sharing & temp access

// Share (expires in 24 hours)
$ss->share('computer-credentials', $secretId, 'bob@example.com',
           'read', date('c', strtotime('+24 hours')));

// Temp access token (15 minutes)
$grant = $ss->createTempAccess('computer-credentials', $secretId, 900);
echo $grant['token'];

Error handling

use SecretServer\AuthException;
use SecretServer\PermissionException;
use SecretServer\NotFoundException;

try {
    $secret = $ss->secret('production/postgres-password');
} catch (NotFoundException $e) {
    // secret does not exist or is outside caller's tenant
} catch (PermissionException $e) {
    // API key lacks the required scope
} catch (AuthException $e) {
    // invalid or expired API key
}

🐹 Go

Idiomatic Go client with full context support and strongly-typed request/response structs.

go get github.com/afterdarksys/secretserver-go

Quick start

import (
    "context"
    "fmt"
    "os"

    ss "github.com/afterdarksys/secretserver-go/secretserver"
)

client, err := ss.NewClient(&ss.Config{
    APIKey: os.Getenv("SS_API_KEY"),
})
if err != nil { ... }

ctx := context.Background()

// Path-based lookup (container/key or container/key/version)
result, err := client.Path.Get(ctx, "production", "postgres-password", 0)
fmt.Println(result.Data["password"])

// Historical version (version=2 → one back)
old, err := client.Path.Get(ctx, "production", "postgres-password", 2)

Generic secrets

// Get by ID
secret, err := client.Secrets.Get(ctx, "uuid", nil)

// Create
created, err := client.Secrets.Create(ctx, &ss.CreateSecretRequest{
    Name:  "my-key",
    Value: "s3cr3t",
    Tags:  map[string]string{"env": "prod"},
})

SSH keys & certificates

// Generate SSH key
key, err := client.SSHKeys.Generate(ctx, &ss.GenerateSSHKeyRequest{
    Name:    "deploy-key",
    KeyType: "ed25519",
})
fmt.Println(key.PublicKey)

// List certificates
certs, err := client.Certificates.List(ctx, nil)

Sharing & temp access

// Share with a user
share, err := client.Sharing.Create(ctx, "computer-credentials", secretID,
    &ss.CreateShareRequest{
        Email:      "bob@example.com",
        Permission: "read",
    })

// Temp access token
grant, err := client.TempAccess.Create(ctx, "computer-credentials", secretID, 900)
fmt.Println(grant.Token)     // store this — shown once

📋 Ansible

A lookup plugin that lets you retrieve secrets directly inside Ansible playbooks. No extra dependencies — uses Python's standard urllib.

Install

# Download to your project's lookup_plugins directory
mkdir -p lookup_plugins
curl -sSL https://raw.githubusercontent.com/afterdarksys/secretserver-clients/main/ansible/secretserver.py \
  -o lookup_plugins/secretserver.py

# Set your API key
export SS_API_KEY=sk_live_...

Usage

- name: Deploy application
  hosts: webservers
  vars:
    db_password: "{{ lookup('secretserver', 'production/db-password') }}"
    api_key:     "{{ lookup('secretserver', 'production/stripe-key') }}"
    # Historical version:
    old_pass:    "{{ lookup('secretserver', 'production/db-password/2') }}"
  tasks:
    - name: Write database config
      template:
        src: db.conf.j2
        dest: /etc/app/db.conf
      no_log: true   # never log secret values

Custom base URL (self-hosted)

- name: Deploy with self-hosted SecretServer
  hosts: all
  vars:
    db_password: "{{ lookup('secretserver', 'production/db-password',
                             base_url='https://secrets.internal') }}"
  tasks: ...

Permission Scopes

API keys carry permission scopes. Assign only the scopes your application requires. The admin:* scope grants all permissions.