{"id":8255,"library":"keeper-secrets-manager-core","title":"Keeper Secrets Manager Core","description":"Keeper Secrets Manager Core is the Python SDK for Keeper's cloud-based, zero-knowledge secrets management platform. It allows developers to securely access and manage sensitive credentials like API keys, database passwords, and SSH keys in CI/CD pipelines, containers, and automation scripts. The library is actively maintained with frequent updates, with the current stable version being 17.2.0.","status":"active","version":"17.2.0","language":"en","source_language":"en","source_url":"https://github.com/Keeper-Security/secrets-manager","tags":["secrets management","security","devops","api keys","passwords","zero-knowledge"],"install":[{"cmd":"pip install keeper-secrets-manager-core","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Minimum Python version required.","package":"python","version":">=3.9"},{"reason":"Used for cryptographic operations, floor raised to resolve CVEs.","package":"cryptography","version":">=46.0.5"},{"reason":"HTTP client library, floor raised to resolve CVEs. Version varies by Python.","package":"urllib3","version":">=2.6.3 (for Python 3.10+), >=1.26.0,<1.27 (for Python 3.6-3.9)"},{"reason":"HTTP client library, floor raised to resolve CVEs.","package":"requests","version":">=2.32.4"}],"imports":[{"symbol":"SecretsManager","correct":"from keeper_secrets_manager_core import SecretsManager"}],"quickstart":{"code":"import os\nfrom keeper_secrets_manager_core import SecretsManager\n\n# The one-time access token is typically generated via Keeper Web Vault or Commander CLI.\n# It's recommended to retrieve it from an environment variable for production.\nONE_TIME_TOKEN = os.environ.get('KEEPER_ONE_TIME_TOKEN', 'US:YOUR_ONE_TIME_TOKEN_HERE') # Replace with your token\n\ntry:\n    # Initialize the Secrets Manager. This will create or load the client-config.json file.\n    # The token is only needed for initial setup; subsequent calls can omit it if config exists.\n    secrets_manager = SecretsManager(token=ONE_TIME_TOKEN)\n    print(\"SecretsManager initialized successfully.\")\n\n    # Retrieve all secrets accessible by the configured device.\n    all_secrets = secrets_manager.get_secrets()\n    if all_secrets:\n        print(f\"Retrieved {len(all_secrets)} secrets.\")\n        for secret in all_secrets:\n            print(f\"  Title: {secret.title}, UID: {secret.uid}\")\n            # Example: Access a standard field like 'password'\n            try:\n                password = secret.field('password', single=True)\n                # print(f\"    Password: {password}\") # WARNING: Do not print sensitive data in production\n            except Exception as e:\n                print(f\"    No 'password' field found or error: {e}\")\n    else:\n        print(\"No secrets found.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure 'KEEPER_ONE_TIME_TOKEN' environment variable is set or the token in code is valid.\")\n    print(\"For initial setup, a one-time access token is required to create `client-config.json`.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `SecretsManager` using a one-time access token (preferably from an environment variable) and retrieve secrets. The one-time token is used for initial device registration and configuration file creation (e.g., `client-config.json`). After the initial setup, the SDK can often be initialized without the token, relying on the local configuration."},"warnings":[{"fix":"Upgrade Python to 3.9 or higher. If unable to upgrade Python, ensure `pip` installs `keeper-secrets-manager-core<17.2.0`.","message":"Minimum Python version raised to 3.9 in `keeper-secrets-manager-core` v17.2.0. Users on Python 3.6-3.8 will automatically install the latest v17.1.x release, which continues to receive security/bug fixes until August 2026.","severity":"breaking","affected_versions":">=17.2.0"},{"fix":"Ensure `client-config.json` retains secure permissions. Environment variables like `KSM_CONFIG_SKIP_MODE` or `KSM_CONFIG_SKIP_MODE_WARNING` can be used to disable permission checking or warnings if necessary.","message":"The SDK creates a `client-config.json` file to store connection and encryption information. On Unix, this file is created with 0600 (owner-only) permissions; on Windows, secure ACLs are applied. Warnings may be issued if permissions are too open.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult your IT team to allow Keeper traffic (to `keepersecurity.com`, `keepersecurity.eu`, etc.) through firewalls without interception. Ensure `verify_ssl_certs` and `proxy_url` parameters are correctly configured for file operations if a proxy is used.","message":"SSL certificate errors (`requests.exceptions.SSLError`) can occur if network proxies attempt packet inspection, as Keeper traffic is encrypted end-to-end and cannot be intercepted.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify that records intended for use with Secrets Manager are 'typed'. Records can be identified as non-typed if they lack a 'Type' field or by using `ls -l` in Keeper Commander CLI.","message":"Keeper Secrets Manager only supports typed records (V3). Attempting to retrieve a legacy, non-typed record will result in a 'record not found' error.","severity":"gotcha","affected_versions":"All"},{"fix":"Generate a new one-time access token from the Keeper Web Vault or Keeper Commander CLI and retry initialization. The token is typically only needed for the *first* initialization to create the local configuration file.","message":"The one-time access token used for initial device registration and configuration (`SecretsManager(token=...)`) can expire. If it expires, SDK initialization will fail.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Allow direct access to Keeper security domains (`keepersecurity.com`, etc.) through your firewall/proxy. If using a proxy, ensure `verify_ssl_certs` and `proxy_url` are configured correctly.","cause":"Network proxy performing packet inspection, or invalid SSL certificate configuration preventing secure connection to Keeper servers.","error":"requests.exceptions.SSLError: HTTPSConnectionPool(...): Max retries exceeded with url: .../authentication/..."},{"fix":"Ensure the record is a 'typed' record (V3) and that the configured device has appropriate permissions to access it. Verify the record UID is correct.","cause":"Attempting to retrieve a legacy (non-V3) or untyped record, which is not supported by Keeper Secrets Manager. Also can occur if the record UID is incorrect or permissions are insufficient.","error":"Record not Found"},{"fix":"Verify that the Secrets Manager add-on is active on your Keeper Account and that the role used by the application/device has the Secrets Manager enforcement policy enabled in the Admin Console.","cause":"The Secrets Manager add-on is not enabled for your Keeper Account, or the role associated with the device does not have the Secrets Manager enforcement policy enabled.","error":"access_denied"},{"fix":"Implement retry logic with exponential backoff in your application to handle throttled requests. Review application design to minimize rapid, repetitive API calls from a single device ID.","cause":"The Keeper Secrets Manager API throttles requests based on the Device ID. Excessive requests from a single device ID can trigger throttling.","error":"Throttling error (e.g., HTTP 503 response code)"},{"fix":"Use the `secret.field('field_name', single=True)` method for standard fields, or iterate if expecting multiple values. Refer to the SDK documentation for correct field access patterns.","cause":"Incorrectly attempting to access a secret field value, possibly confusing the `field()` method (which returns a specific field) with direct attribute access, or misinterpreting multi-value fields.","error":"TypeError: 'list' object is not callable (or similar when accessing a record field)"}]}