Keeper Secrets Manager Core

Common errors

• requests.exceptions.SSLError: HTTPSConnectionPool(...): Max retries exceeded with url: .../authentication/...

  cause Network proxy performing packet inspection, or invalid SSL certificate configuration preventing secure connection to Keeper servers.
  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.

• Record not Found

  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.
  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.

• access_denied

  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.
  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.

• Throttling error (e.g., HTTP 503 response code)

  cause The Keeper Secrets Manager API throttles requests based on the Device ID. Excessive requests from a single device ID can trigger throttling.
  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.

• TypeError: 'list' object is not callable (or similar when accessing a record field)

  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.
  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.

Warnings

• breaking 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.
  Fix: Upgrade Python to 3.9 or higher. If unable to upgrade Python, ensure `pip` installs `keeper-secrets-manager-core<17.2.0`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha Keeper Secrets Manager only supports typed records (V3). Attempting to retrieve a legacy, non-typed record will result in a 'record not found' error.
  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.
• gotcha The one-time access token used for initial device registration and configuration (`SecretsManager(token=...)`) can expire. If it expires, SDK initialization will fail.
  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.

Install

• pip install keeper-secrets-manager-core Install stable version

Imports

• SecretsManager

  from keeper_secrets_manager_core import SecretsManager

Quickstart

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.

import os
from keeper_secrets_manager_core import SecretsManager

# The one-time access token is typically generated via Keeper Web Vault or Commander CLI.
# It's recommended to retrieve it from an environment variable for production.
ONE_TIME_TOKEN = os.environ.get('KEEPER_ONE_TIME_TOKEN', 'US:YOUR_ONE_TIME_TOKEN_HERE') # Replace with your token

try:
    # Initialize the Secrets Manager. This will create or load the client-config.json file.
    # The token is only needed for initial setup; subsequent calls can omit it if config exists.
    secrets_manager = SecretsManager(token=ONE_TIME_TOKEN)
    print("SecretsManager initialized successfully.")

    # Retrieve all secrets accessible by the configured device.
    all_secrets = secrets_manager.get_secrets()
    if all_secrets:
        print(f"Retrieved {len(all_secrets)} secrets.")
        for secret in all_secrets:
            print(f"  Title: {secret.title}, UID: {secret.uid}")
            # Example: Access a standard field like 'password'
            try:
                password = secret.field('password', single=True)
                # print(f"    Password: {password}") # WARNING: Do not print sensitive data in production
            except Exception as e:
                print(f"    No 'password' field found or error: {e}")
    else:
        print("No secrets found.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure 'KEEPER_ONE_TIME_TOKEN' environment variable is set or the token in code is valid.")
    print("For initial setup, a one-time access token is required to create `client-config.json`.")