IBM Cloud Platform Services Python SDK

Warnings

• gotcha Each 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.
  Fix: Ensure you import the correct service client class, e.g., `from ibm_platform_services.iam_identity_v1 import IamIdentityV1` for the IAM Identity service.
• gotcha Authentication 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.
  Fix: Initialize 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.
• gotcha Being 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.
  Fix: Pin the library version in your `requirements.txt` or `pyproject.toml` (e.g., `ibm-platform-services==0.75.0`). Regularly review changelogs for new versions.
• gotcha The 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.
  Fix: Ensure your development and deployment environments are running Python 3.10 or a more recent version (e.g., Python 3.11, 3.12).

Install

• pip install ibm-platform-services Install latest version

Imports

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

Quickstart

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