Keeper Secrets Manager Python SDK

For more information, see our official documentation page https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/python-sdk

Python Requirements: Python 3.9 or higher

Custom Server Public Key (Isolated Deployments)

For deployments where the server public key is not shipped with the SDK, a caller-supplied EC P-256 public key can be supplied via any of three paths (precedence is programmatic > one-time token > pre-existing config):

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

# Programmatic — wins over the other two if all are present
sm = SecretsManager(
    token='REGION:ONE_TIME_TOKEN',
    server_public_key='url-safe-base64-EC-P256-public-key',
    server_public_key_id='your-key-id',
    config=FileKeyValueStorage(),
)

The one-time-token form embeds the key material directly: REGION:clientKey:keyId:serverPublicKeyBase64 (4 colon-separated segments). The config-file form sets serverPublicKey and serverPublicKeyId in the JSON config before the first call.

For deployment-specific details (region prefixes, key id assignments) see the official docs link above.

Change Log

17.3.0

• KSM-992 - Added a typed KeeperRecordLink linked-credential accessor layer and Record.get_links(). Provides Java-parity accessors (is_admin_user(), is_launch_credential(), permission booleans such as allows_rotation()/allows_connections(), get_link_data_version(), get_decoded_data(), encryption detection, AES-256-GCM get_decrypted_data(), get_link_data(), and get_ai_settings_data()/get_jit_settings_data()/get_settings_for_path()) plus accessors for the current link payload shape verified against the live backend: meta self-links (get_meta_data(), get_allowed_settings()), is_iam_user(), belongs_to(), no_update_services(), ai_enabled(), ai_session_terminate() and get_rotation_settings(). Permission booleans read both top-level keys and the nested allowedSettings. Purely additive — the raw record.links list is unchanged, and each typed link keeps the untouched original dict in .raw.
• KSM-877 - Added automatic throttle retry with exponential backoff. On HTTP 403 {"error":"throttled"}, requests are retried up to 5 times with exponentially increasing delays (11s, 22s, 44s, 88s, 176s) plus ±25% jitter, honoring retry_after from the response when present; a typed KeeperThrottleError (subclass of KeeperError) is raised once retries are exhausted. Existing key-rotation retry behavior is unchanged.
• KSM-807 - Fixed partial client-config.json left behind after a failed initialization (expired or consumed One-Time Token). The SDK now deletes the incomplete config file on failure so users are not silently trapped in a retry loop. The error message names the file and instructs the user to generate a fresh token.
• KSM-932 - IL5 custom server public key support — supports three provisioning paths: config field (serverPublicKey), OTS token extension (4-segment IL5 format), and programmatic parameter (server_public_key on SecretsManager)
• KSM-808 - Config-decoding utilities (base64_to_bytes, url_safe_str_to_bytes, base64_to_string, CryptoUtils.url_safe_str_to_bytes) now raise KeeperError with actionable messages instead of cryptic TypeError when passed None from an incomplete config or empty server response field. Per-call-site guards in core.py name the specific missing ConfigKey (appKey, clientKey) and direct users to reinitialize with a fresh One-Time Token.
• KSM-813 - Fixed set_config_mode() Windows ACL sequence to remove all Everyone access (not just Full Control)
• KSM-819 - Fixed RecordCreate.to_dict() silently dropping "custom": [] from the serialized payload (Python falsy check treated empty list as absent). Records created via the SDK now correctly include "custom": [], matching Commander and Vault behavior.
• KSM-1004 - KSMCache now resolves the cache file path from KSM_CACHE_DIR at call time instead of once at import. The documented env var is honored whenever it is set, not only when set before keeper_secrets_manager_core.core is imported. Default behavior is unchanged (ksm_cache.bin in the current working directory when the var is unset).

17.2.1

• KSM-900 - Added IL5 (DoD Impact Level 5) region support — token prefix IL5 resolves to il5.keepersecurity.us

17.2.0

• Breaking: Minimum Python version raised from 3.6 to 3.9
  • Python 3.6-3.8 users: pip will automatically install v17.1.x (no action needed)
  • Security/bug fixes backported to v17.1.x until August 2026 via legacy/sdk/python/core/v17.1.x branch
• Security: KSM-777 - Raised dependency floors to resolve multiple CVEs
  • cryptography>=46.0.5 (was >=39.0.1, resolves CVE-2026-26007 elliptic curve vulnerability)
  • urllib3>=2.6.3 unconditionally (was split between urllib3 1.x/2.x, resolves CVE-2026-21441, CVE-2025-66471, CVE-2025-66418, CVE-2025-50181, CVE-2025-50182)
  • requests>=2.32.4 (resolves CVE-2024-47081 .netrc credentials leak)
• Removed importlib_metadata dependency (stdlib importlib.metadata available since Python 3.8)
• Added Python 3.13 support and CI testing

17.1.0

• Security: KSM-760 - Fixed CVE-2026-23949 (jaraco.context path traversal) in SBOM generation workflow
  • Upgraded jaraco.context to >= 6.1.0 in SBOM build environment
  • Build-time dependency only, does not affect runtime or published packages
• Security: Added version-specific urllib3 dependency to address CVE-2025-66418 and CVE-2025-66471 (HIGH severity)
  • Python 3.10+: uses urllib3>=2.6.0 (latest security fixes)
  • Python 3.6-3.9: uses urllib3>=1.26.0,<1.27 (compatible with boto3/AWS storage)
• Security: KSM-695 - Fixed file permissions for client-config.json (created with 0600 permissions)
• KSM-763 - Fixed file upload/download operations failing when using proxy with verify_ssl_certs=False
  • Added verify_ssl_certs and proxy_url parameters to file upload/download functions
  • Previously, these settings were ignored, causing SSL verification errors when using proxies
• KSM-749 - Fixed client version detection to prevent stale .dist-info metadata causing "invalid client version id" errors
  • Introduced single source of truth for version via _version.py
  • Client version now prioritizes package version attribute over importlib_metadata
  • Fixes issue where package upgrades left stale metadata causing backend authentication failures
• KSM-740 - Added transmission public key #18 for Gov Cloud Dev support
• KSM-732 - Fixed notation lookup when record shortcuts exist (duplicate UID handling)
• KSM-650 - Improved error messages for malformed configuration files
• KSM-628 - Added GraphSync links support

17.0.0

• KSM-566 - Added parsing for KSM tokens with prefix
• KSM-631 - Added links2Remove parameter for files removal
• KSM-635 - HTTPError should include response object

16.6.6

• KSM-552 - Stop generating UIDs that start with "-"

16.6.5

• KSM-529 - Handle broken encryption in records and files

16.6.4

• KSM-488 - Remove unused package dependencies

16.6.3

• KSM-479 - Remove dependency on distutils due to Python 3.12 removing it

16.6.2

• KSM-463 - Python SDK - Fix a bug when fields is null
• KSM-458 - Python SDK - Remove core's dependency on the helper module. Fixes issue 488

16.6.1

• KSM-444 - Python - Added folderUid and innerFolderUid to Record

16.6.0

• KSM-413 - Added support for Folders
• KSM-434 - Improved Passkey field type support

16.5.4

• KSM-405 - Added new script field type and oneTimeCode to PAM record types
• KSM-410 - New field type: Passkey
• KSM-394 - Ability to load configuration from AWS Secrets Manager using AWS AIM role in EC2 instance or AWS IAM user
• KSM-416 - Fix OS detection bug
• KSM-400 - Unpinned few dependencies

16.5.3

• KSM-393 - Fix file permissions on localized Windows OS

16.5.2

• KSM-375 - Make HTTPError to be more informative
• KSM-376 - Support for PAM record types
• KSM-381 - Transactions
• Fixed Issue 441 - Bug caused by space in username

16.5.1

• KSM-371 - Fix Windows Config file permissions issue
• KSM-370 - Upgrade to latest cryptography>=39.0.1 library

16.5.0

• KSM-313 - Improved Keeper Notations. New parser, new escape characters, Notation URI, search records by title and other meta data values in the record
• KSM-319 - KEY_CLIENT_KEY in configurations is missing in certain situations
• KSM-356 - Ability to create of the new custom field

16.4.2

• Fix to support dynamic client version

16.4.1

• Upgrading and pinning cryptography dependency to 38.0.3

16.4.0

• Record deletion
• KSM-305 - Support for Canada and Japan data centers
• KSM-308 - Improve password generation entropy
• KSM-240 - Config file permission checking (Create new client-config.json with locked down permission/ACL mode. Print STDERR warning if client-config.json ACL mode is too open. To disable ACL mode checking and setting, set environmental variable KSM_CONFIG_SKIP_MODE to TRUE. To prevent warnings of the client-config.json being too open, set environmental variable KSM_CONFIG_SKIP_MODE_WARNING to TRUE. For Unix, client-config.json is set to 0600 mode. For Windows, client-config.json has only the user that created the client-config.json and the Administrator group.)

16.3.5

• Removed non-ASCII characters from source code. Added Python comment flag to allow non-ASCII to source code, just in case.
• Allow enforceGeneration, privacyScreen, and complexity in record fields when creating a record.
• Record creation validation. Making sure that only legitimate record field types, notes section, and title of the record can be saved

16.3.4

• Provide better exception messages when the config JSON file is not utf-8 encoded.