Install & Compatibility
Where this runs
tested against v0.77.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.628s · 29.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.582s · 30MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
IamIdentityV1
✓ from ibm_platform_services.iam_identity_v1 import IamIdentityV1
Most service clients follow the pattern `ibm_platform_services.<service_name>_v<version_number>`.
IAMAuthenticator
✓ from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
Authenticators are provided by `ibm-cloud-sdk-core`, a required dependency.
This quickstart demonstrates how to authenticate with an IBM Cloud API key and initialize the IAM Identity service client to list account settings. Replace `YOUR_IBMCLOUD_API_KEY` or set the `IBMCLOUD_API_KEY` environment variable. The `IBMCLOUD_IAM_IDENTITY_SERVICE_URL` is optional, defaulting to the global IAM endpoint.
import os
from ibm_platform_services.iam_identity_v1 import IamIdentityV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
from ibm_cloud_sdk_core.detailed_response import DetailedResponse
# Configure API key and service URL
api_key = os.environ.get("IBMCLOUD_API_KEY", "YOUR_IBMCLOUD_API_KEY")
service_url = os.environ.get("IBMCLOUD_IAM_IDENTITY_SERVICE_URL", "https://iam.cloud.ibm.com")
if api_key == "YOUR_IBMCLOUD_API_KEY":
print("Please set the IBMCLOUD_API_KEY environment variable or replace 'YOUR_IBMCLOUD_API_KEY' with your actual IBM Cloud API key.")
exit(1)
try:
# 1. Authenticate using IAMAuthenticator
authenticator = IAMAuthenticator(api_key)
# 2. Initialize the service client (e.g., IAM Identity Service)
iam_identity_service = IamIdentityV1(authenticator=authenticator)
iam_identity_service.set_service_url(service_url)
# 3. Perform an operation (e.g., list account settings)
print("Attempting to list account settings...")
response: DetailedResponse = iam_identity_service.list_account_settings().get_result()
print("Successfully retrieved account settings (first 200 chars):\n")
print(str(response)[:200] + ('...' if len(str(response)) > 200 else ''))
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your API key and service URL are correct and you have the necessary permissions.")
Debug
Known issues
gotchaEach IBM Cloud service and its API version (e.g., `_v1`, `_v2`) has a distinct client class (e.g., `IamIdentityV1`, `GlobalTaggingV1`). Users must import the specific client for the service and version they intend to use.fixEnsure you import the correct service client class, e.g., `from ibm_platform_services.iam_identity_v1 import IamIdentityV1` for the IAM Identity service.
affects: All versions
gotchaAuthentication relies on `ibm_cloud_sdk_core` authenticators (e.g., `IAMAuthenticator`), which require an IBM Cloud API key (or other credentials) and often an explicit service endpoint URL. Incorrect setup leads to authentication or connection errors.fixInitialize your authenticator correctly (e.g., `IAMAuthenticator(api_key)`) and call `service_client.set_service_url()` if not using the default global endpoint. Prefer environment variables (`IBMCLOUD_API_KEY`, `IBMCLOUD_<SERVICE_NAME>_SERVICE_URL`) for configuration.
affects: All versions
gotchaBeing in `0.x.x` version range, the library API could introduce breaking changes in minor versions, although recent releases tend to be additive. For production environments, it is recommended to pin the exact version to prevent unexpected issues.fixPin the library version in your `requirements.txt` or `pyproject.toml` (e.g., `ibm-platform-services==0.75.0`). Regularly review changelogs for new versions.
affects: All versions < 1.0.0
gotchaThe library explicitly requires Python 3.10 or newer. Attempting to install or run with older Python versions (e.g., 3.9 or earlier) will result in installation failures or runtime errors.fixEnsure your development and deployment environments are running Python 3.10 or a more recent version (e.g., Python 3.11, 3.12).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ibm_platform_services.<service-module-name>'
The user is attempting to import a service client using an incorrect or non-existent module name within the `ibm_platform_services` package.
fixEnsure the service module name is correct as documented for the specific IBM Cloud service you intend to use (e.g., `from ibm_platform_services.iam_identity_v1 import IamIdentityV1`).
Authentication failed
The IBM Cloud API key is incorrect, missing, or the service client's authenticator or service endpoint URL is not configured correctly, preventing successful authentication with the IBM Cloud service.
fixInitialize the `IAMAuthenticator` with a valid IBM Cloud API key. If necessary, explicitly set the service URL using `service_client.set_service_url()` if not using the default global endpoint.
ValueError: '<parameter_name>' is required
A required parameter for a specific service API method call was either omitted or provided with an invalid value.
fixConsult the official documentation or the SDK's method signature for the specific service client and method to identify and provide all necessary parameters with valid values.
Upgrade
Version history
0.77.0latest on PyPI · released Jul 22, 2026
Audit
Dependencies
ibm-cloud-sdk-corerequiredProvides core functionalities including authenticators and base service models, essential for client interaction.