{"id":7299,"library":"ibm-secrets-manager-sdk","title":"IBM Cloud Secrets Manager Python SDK","description":"The `ibm-secrets-manager-sdk` is the official Python SDK for interacting with IBM Cloud Secrets Manager. It provides programmatic access to store, manage, and retrieve secrets like API keys, passwords, and certificates. Currently at version 2.1.19, the library maintains a frequent release cadence, often incorporating bug fixes, new secret types, and support for service features, as well as dependency updates.","status":"active","version":"2.1.19","language":"en","source_language":"en","source_url":"https://github.com/IBM/secrets-manager-python-sdk","tags":["ibm-cloud","secrets","security","sdk","cloud-native","iam"],"install":[{"cmd":"pip install ibm-secrets-manager-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides core functionalities for IBM Cloud SDKs, including authentication and service request handling.","package":"ibm-cloud-sdk-core","optional":false}],"imports":[{"symbol":"SecretsManagerV2","correct":"from ibm_secrets_manager_sdk.secrets_manager_v2 import SecretsManagerV2"},{"note":"Required for authenticating with IBM Cloud services using an API key.","symbol":"IAMAuthenticator","correct":"from ibm_cloud_sdk_core.authenticators import IAMAuthenticator"}],"quickstart":{"code":"import os\nfrom ibm_secrets_manager_sdk.secrets_manager_v2 import SecretsManagerV2\nfrom ibm_cloud_sdk_core.authenticators import IAMAuthenticator\n\n# Configure IBM Cloud API Key and Secrets Manager Service URL\n# It is highly recommended to use environment variables for credentials.\napi_key = os.environ.get(\"IBM_CLOUD_API_KEY\", \"YOUR_IBM_CLOUD_API_KEY\")\nservice_url = os.environ.get(\"IBM_SECRETS_MANAGER_URL\", \"YOUR_SECRETS_MANAGER_URL\") # e.g., 'https://<region>.secrets-manager.appdomain.cloud/api'\n\nif api_key == \"YOUR_IBM_CLOUD_API_KEY\" or service_url == \"YOUR_SECRETS_MANAGER_URL\":\n    print(\"WARNING: Please set IBM_CLOUD_API_KEY and IBM_SECRETS_MANAGER_URL environment variables or replace placeholders.\")\n    # For demonstration, we'll proceed, but real applications require valid credentials.\n    # raise ValueError(\"Missing IBM_CLOUD_API_KEY or IBM_SECRETS_MANAGER_URL environment variable.\")\n\n# Initialize authenticator\nauthenticator = IAMAuthenticator(api_key)\n\n# Initialize the Secrets Manager service client\nsecrets_manager_service = SecretsManagerV2(\n    authenticator=authenticator\n)\nsecrets_manager_service.set_service_url(service_url)\n\ntry:\n    # Example: List up to 10 secrets in your instance\n    list_secrets_response = secrets_manager_service.list_secrets(\n        limit=10\n    ).get_result()\n\n    if list_secrets_response and list_secrets_response.resources:\n        print(f\"Successfully retrieved {len(list_secrets_response.resources)} secrets:\")\n        for secret in list_secrets_response.resources:\n            print(f\"- ID: {secret.id}, Name: {secret.name}, Type: {secret.secret_type}\")\n    else:\n        print(\"No secrets found in the specified instance.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `SecretsManagerV2` client using an IAM API key and then list the secrets available in your IBM Cloud Secrets Manager instance. Ensure `IBM_CLOUD_API_KEY` and `IBM_SECRETS_MANAGER_URL` environment variables are set with your credentials and service endpoint."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or later.","message":"The SDK requires Python 3.9 or newer. Using older Python versions will result in installation failures or runtime errors.","severity":"gotcha","affected_versions":"<2.1.x"},{"fix":"Always configure the `service_url` with the correct region endpoint for your Secrets Manager instance. Refer to IBM Cloud documentation for regional endpoints.","message":"IBM Cloud Secrets Manager service URLs are region-specific (e.g., `https://us-south.secrets-manager.appdomain.cloud/api`). Using a wrong or generic URL can lead to connectivity issues or 'Resource Not Found' errors, even with correct authentication.","severity":"gotcha","affected_versions":"All v2.x versions"},{"fix":"Ensure you are using `v2.1.13` or newer if your application relies on the `retrieved_at` field. Handle potential `AttributeError` gracefully if supporting `v2.1.12`.","message":"The `retrieved_at` field, which indicates when secret data was last accessed, was introduced in an earlier minor version, then temporarily reverted in `v2.1.12`, and re-added in `v2.1.13`. Code relying on this field might encounter `AttributeError` if deployed with `v2.1.12`.","severity":"gotcha","affected_versions":"v2.1.12"},{"fix":"Consult the official migration guide for `ibm-cloud-sdk-core` and the `ibm-secrets-manager-sdk` documentation for `v2.x` to adapt your code. Key changes include updated import paths and method parameters.","message":"Upgrading from `v1.x` to `v2.x` of IBM Cloud SDKs, including Secrets Manager, generally involves breaking changes due to module restructuring, API method signature changes, and updated object models. Direct migration without code changes will likely fail.","severity":"breaking","affected_versions":"Migration from v1.x to v2.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install ibm-secrets-manager-sdk` to install the library.","cause":"The `ibm-secrets-manager-sdk` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'ibm_secrets_manager_sdk'"},{"fix":"Verify your `IBM_CLOUD_API_KEY` is correct, active, and has the necessary IAM roles (e.g., Viewer, Manager) for the Secrets Manager instance. Ensure the service URL matches your instance's region.","cause":"The provided IBM Cloud API key is either invalid, expired, or does not have sufficient permissions to access the Secrets Manager service.","error":"ibm_cloud_sdk_core.authenticators.authenticator.ApiException: Error: Unauthorized. Code: 401 Unauthorized"},{"fix":"Ensure you call `secrets_manager_service.set_service_url(YOUR_SECRETS_MANAGER_URL)` with a valid and non-empty service endpoint for your Secrets Manager instance (e.g., from an environment variable).","cause":"The `set_service_url()` method was not called on the `SecretsManagerV2` client, or the provided `service_url` was an empty string.","error":"ValueError: Service url is required."},{"fix":"Upgrade to `ibm-secrets-manager-sdk==2.1.13` or a newer version where the `retrieved_at` field has been re-introduced. Alternatively, add checks to your code to gracefully handle its absence.","cause":"You are attempting to access the `retrieved_at` field on a secret object while using `ibm-secrets-manager-sdk` version `v2.1.12`, where this field was temporarily unavailable.","error":"AttributeError: 'SecretResource' object has no attribute 'retrieved_at'"}]}