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.
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 internalput()fallback also fails with409(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.
fetch()¶
Fetches a secret's ciphertext from the server and decrypts it locally in one call.
| 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.
list_secrets()¶
Lists every secret in the catalog (metadata only — does not return values or trigger decryption).
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.