IBM Cloud Secrets Manager Python SDK

2.1.19 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'ibm_secrets_manager_sdk'
```
cause The `ibm-secrets-manager-sdk` library is not installed in the current Python environment.

fix Run `pip install ibm-secrets-manager-sdk` to install the library.
```
ibm_cloud_sdk_core.authenticators.authenticator.ApiException: Error: Unauthorized. Code: 401 Unauthorized
```
cause The provided IBM Cloud API key is either invalid, expired, or does not have sufficient permissions to access the Secrets Manager service.

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.
```
ValueError: Service url is required.
```
cause The `set_service_url()` method was not called on the `SecretsManagerV2` client, or the provided `service_url` was an empty string.

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).
```
AttributeError: 'SecretResource' object has no attribute 'retrieved_at'
```
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.

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.

Warnings

gotcha The SDK requires Python 3.9 or newer. Using older Python versions will result in installation failures or runtime errors.
Fix: Upgrade your Python environment to 3.9 or later.
gotcha 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.
Fix: Always configure the `service_url` with the correct region endpoint for your Secrets Manager instance. Refer to IBM Cloud documentation for regional endpoints.
gotcha 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`.
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`.
breaking 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.
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.

Install

pip install ibm-secrets-manager-sdk Install latest version

Imports

SecretsManagerV2

from ibm_secrets_manager_sdk.secrets_manager_v2 import SecretsManagerV2

IAMAuthenticator
```
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
```
Required for authenticating with IBM Cloud services using an API key.

Quickstart

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.

import os
from ibm_secrets_manager_sdk.secrets_manager_v2 import SecretsManagerV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Configure IBM Cloud API Key and Secrets Manager Service URL
# It is highly recommended to use environment variables for credentials.
api_key = os.environ.get("IBM_CLOUD_API_KEY", "YOUR_IBM_CLOUD_API_KEY")
service_url = os.environ.get("IBM_SECRETS_MANAGER_URL", "YOUR_SECRETS_MANAGER_URL") # e.g., 'https://<region>.secrets-manager.appdomain.cloud/api'

if api_key == "YOUR_IBM_CLOUD_API_KEY" or service_url == "YOUR_SECRETS_MANAGER_URL":
    print("WARNING: Please set IBM_CLOUD_API_KEY and IBM_SECRETS_MANAGER_URL environment variables or replace placeholders.")
    # For demonstration, we'll proceed, but real applications require valid credentials.
    # raise ValueError("Missing IBM_CLOUD_API_KEY or IBM_SECRETS_MANAGER_URL environment variable.")

# Initialize authenticator
authenticator = IAMAuthenticator(api_key)

# Initialize the Secrets Manager service client
secrets_manager_service = SecretsManagerV2(
    authenticator=authenticator
)
secrets_manager_service.set_service_url(service_url)

try:
    # Example: List up to 10 secrets in your instance
    list_secrets_response = secrets_manager_service.list_secrets(
        limit=10
    ).get_result()

    if list_secrets_response and list_secrets_response.resources:
        print(f"Successfully retrieved {len(list_secrets_response.resources)} secrets:")
        for secret in list_secrets_response.resources:
            print(f"- ID: {secret.id}, Name: {secret.name}, Type: {secret.secret_type}")
    else:
        print("No secrets found in the specified instance.")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →