Skip to content

User Guide

The public surface of VaultSDK is deliberately small: create, put, fetch, and list_secrets. Everything else (request signing, retries, KMS key management) is an internal implementation detail and is not part of the supported API.

from cps_vault_sdk import VaultSDK

sdk = VaultSDK()

create()

Encrypts plaintext with KMS and creates a new secret. Falls back to put() if the secret already exists (409).

sdk.create(
    secret_name: str,
    plaintext: str | dict,
    application_name: str,
    ttl: str,
    cps_project_name: str,
    description: str | None = None,
) -> dict
Parameter Type Required Description
secret_name str yes Name of the secret. May contain / (e.g. "my-app/db-password").
plaintext str \| dict yes Secret value to encrypt. A dict is JSON-serialized before encryption.
application_name str yes Owning application name, for the catalog.
ttl str yes Short-hand duration: "10m", "6h", "30d", "2w", "3mo", "1y" (between 10 minutes and 2 years). Not a calendar date.
cps_project_name str yes Owning CPS project name, for the catalog.
description str \| None no Optional free-text description.

Returns: server response dict, e.g. {"message": ..., "name": ..., "version_id": ...}.

Raises:

  • SecretAlreadyExistsError — the secret exists and the internal put() fallback also fails with 409 (should not normally happen).
  • ValidationError — the server rejected the request body.
  • VaultError — any other non-2xx response.
sdk.create(
    "my-app/db-password", "s3cr3t!",
    application_name="my-app",
    ttl="6h",
    cps_project_name="cps-project-1",
    description="Primary DB password",
)

put()

Full update: replaces the secret's value and refreshes its tags.

sdk.put(
    secret_name: str,
    plaintext: str | dict,
    ttl: str,
    cps_project_name: str,
    application_name: str | None = None,
    description: str | None = None,
) -> dict
Parameter Type Required Description
secret_name str yes Name of the secret to update.
plaintext str \| dict yes New secret value to encrypt.
ttl str yes New short-hand duration (same format as create()).
cps_project_name str yes Owning CPS project name.
application_name str \| None no If omitted, the existing value on the server is left unchanged.
description str \| None no If omitted, the existing value on the server is left unchanged.

Returns: server response dict, e.g. {"message": ..., "name": ...}.

Raises: ValidationError, SecretNotFoundError, or VaultError for other non-2xx responses.

sdk.put("my-app/db-password", "n3w-s3cr3t!", ttl="6h", cps_project_name="cps-project-1")

fetch()

Fetches a secret's ciphertext from the server and decrypts it locally in one call.

sdk.fetch(secret_name: str) -> str
Parameter Type Required Description
secret_name str yes Name of the secret to retrieve.

Returns: the decrypted plaintext as a str. If the original plaintext passed to create/put was a dict, you'll get back its JSON-serialized string form — deserialize it yourself with json.loads(...) if needed.

Raises: SecretNotFoundError if no secret with this name exists.

value = sdk.fetch("my-app/db-password")

list_secrets()

Lists every secret in the catalog (metadata only — does not return values or trigger decryption).

sdk.list_secrets() -> dict

Returns:

{
    "secrets": [
        {"name": "my-app/db-password", "description": "...", "last_changed": "..."},
        ...
    ],
    "count": 1,
}
catalog = sdk.list_secrets()
for secret in catalog["secrets"]:
    print(secret["name"], secret["last_changed"])

Method summary

Method Purpose Touches KMS Touches server
create() Create a new secret (or update if it already exists) Encrypt Write
put() Replace an existing secret's value + tags Encrypt Write
fetch() Retrieve and decrypt a secret's value Decrypt Read
list_secrets() List catalog metadata for all secrets — Read

See Error Handling for the full exception reference, and Configuration for constructor options.