Skip to content

Configuration

VaultSDK(...) constructor

VaultSDK(
    server_url: str = "https://cps-vault.commandcentral.com",
    aws_profile: str | None = None,
    aws_access_key_id: str | None = None,
    aws_secret_access_key: str | None = None,
    region: str = "us-east-1",
    kms_key_alias: str | None = None,
    timeout: float = 10.0,
    max_retries: int = 2,
    sts_region: str = "us-east-1",
)
Parameter Type Default Description
server_url str "https://cps-vault.commandcentral.com" Base URL of the CPS-Vault server to talk to (the API Gateway custom domain).
aws_profile str \| None None Named AWS CLI profile to sign requests and perform KMS operations with. If omitted, falls back to the default boto3 credential resolution chain (environment variables, instance/task role, SSO, etc).
aws_access_key_id str \| None None Explicit AWS access key, if not using a profile or the default chain.
aws_secret_access_key str \| None None Explicit AWS secret key, paired with aws_access_key_id.
region str "us-east-1" AWS region used for KMS operations.
kms_key_alias str \| None "alias/cps-vault-key" KMS key alias used for client-side envelope encryption. The alias/ prefix is added automatically if omitted. If no key with this alias exists yet in the caller's account, one is created automatically on first use.
timeout float 10.0 Per-request HTTP timeout (seconds) for calls to the server.
max_retries int 2 Automatic retries for transient HTTP failures (connection errors, 429/502/503/504). Applies to all request methods; only raise this if a retried write being re-applied (in case the original request succeeded but its response was lost) is acceptable for your use case.
sts_region str "us-east-1" Region whose STS endpoint the identity proof is signed for. This must be the region of the server's STS endpoint, so you normally never change it. Your own profile/session region is ignored for proofs, which is why callers in any AWS region (and any account) work without extra setup.

Credential resolution order

Internally, the SDK always constructs a boto3.Session(profile_name=aws_profile, aws_access_key_id=aws_access_key_id, aws_secret_access_key=aws_secret_access_key). If you pass none of these three, this is equivalent to boto3.Session() and boto3's normal default credential chain applies.

KMS key lifecycle

  • The SDK resolves its KMS key lazily — nothing is created at construction time, only on the first create/put/fetch call.
  • Resolution looks up an existing key by the configured alias in the caller's own AWS account (kms:DescribeKey equivalent). If none exists, the SDK creates a new key and alias (kms:CreateKey + kms:CreateAlias).
  • Every VaultSDK instance using the same kms_key_alias (and the same underlying AWS account) shares the same physical key, so secrets encrypted by one instance/process can be decrypted by another with the same alias and sufficient IAM permissions.
  • Automatic rotation. When the SDK creates a new key, it also enables automatic annual key rotation on it (kms:EnableKeyRotation equivalent) — no action needed from you, and no impact on existing ciphertext, which continues to decrypt correctly against prior key material.

Choosing a kms_key_alias

Use a distinct alias per application/team if you want to scope KMS key policies (who can decrypt) more narrowly than "everyone who can assume a role in this account." If omitted, all callers in the same AWS account share the default alias/cps-vault-key.

Logging

The SDK logs under the cps_vault_sdk logger name (standard library logging). Enable debug logging to see request timing (including KMS encrypt/decrypt duration):

import logging
logging.getLogger("cps_vault_sdk").setLevel(logging.DEBUG)
logging.basicConfig(level=logging.DEBUG)