Python

pip install "git+https://github.com/afterdarksys/secretserver-clients.git#subdirectory=python"

# or from a checkout
git clone https://github.com/afterdarksys/secretserver-clients.git
pip install ./secretserver-clients/python

# or, for development (editable install)
pip install -e ./secretserver-clients/python

# check the import
python -c "from secretserver import SecretServerClient; print('OK')"

from secretserver import SecretServerClient

# Reads SS_API_KEY and SS_API_URL from the environment when not passed.
ss = SecretServerClient()

# Or pass everything explicitly.
ss = SecretServerClient(
    api_key="sk_...",
    api_url="https://api.secretserver.io",
    timeout=10,                    # seconds
    ca_file="/etc/ssl/private-ca.pem",  # optional private CA, added to system roots
)

# Value only: name, container/key, or container/key/version (1..12)
password = ss.secret("db-password")
password = ss.secret("production/db-password")
previous = ss.secret("production/db-password/2")

# Full record. A read by name also carries the ETag header.
record = ss.get_secret("db-password")
print(record["data"]["value"], record.etag)

ss.create_secret(
    "db-password",
    "s3cr3t",
    description="Primary database",
    container_id="3f0c...uuid",   # a container UUID, not its slug
)

# Safe on any server: prove support with the ETag from a read
record = ss.get_secret("db-password")
ss.update_secret("db-password", "new-value", if_match=record.etag)

# Or opt in when the server is build 3075630 or newer
ss = SecretServerClient(partial_updates=True)   # or SS_PARTIAL_UPDATES=1
ss.update_secret("db-password", description=None)  # clear description only

ss.delete_secret("db-password")

for s in ss.list_secrets():
    print(s["name"], s.get("version"))

from secretserver import (
    SecretServerClient, SecretServerError,
    AuthError, PermissionError, NotFoundError, ConflictError,
)

try:
    value = ss.secret("production/db-password")
except NotFoundError:
    value = None
except (AuthError, PermissionError) as exc:
    raise SystemExit(f"access denied (HTTP {exc.status_code})")
except SecretServerError as exc:
    raise SystemExit(f"secretserver request failed: {exc}")

rotate_example.py

import os
import sys

from secretserver import ConflictError, NotFoundError, SecretServerClient, SecretServerError


def main() -> int:
    ss = SecretServerClient()  # SS_API_KEY / SS_API_URL from the environment
    name = "example-api-token"

    try:
        record = ss.get_secret(name)
    except NotFoundError:
        ss.create_secret(name, "first-value", description="created by example")
        record = ss.get_secret(name)

    try:
        ss.update_secret(name, "second-value", if_match=record.etag)
    except ConflictError as exc:
        print(f"changed by someone else, current ETag {exc.etag}", file=sys.stderr)
        return 1

    names = [s["name"] for s in ss.list_secrets()]
    print(f"{len(names)} secrets visible to this key")
    print("previous value length:", len(ss.secret(name)))
    return 0


if __name__ == "__main__":
    try:
        sys.exit(main())
    except SecretServerError as exc:
        print(f"error: {exc}", file=sys.stderr)
        sys.exit(2)