IBM Cloud SDK Core Library

Common errors

• ModuleNotFoundError: No module named 'ibm_cloud_sdk_core'

  cause The `ibm-cloud-sdk-core` library is not installed in the Python environment.
  fix Install the library using pip: `python -m pip install --upgrade ibm-cloud-sdk-core`

• 401 Unauthorized: Access is denied due to invalid credentials.

  cause The credentials (e.g., API key, bearer token, username/password) provided for authentication are incorrect, expired, or lack the necessary permissions for the requested operation or service endpoint. This often includes specific messages like 'invalid_grant' indicating a problem with obtaining or refreshing an access token.
  fix Verify that your API key is correct and active, the service endpoint URL is accurate for your region, and the authenticated identity has the required IAM roles and permissions. Ensure IAM access tokens are correctly generated and refreshed, or provide valid `username` and `password` for basic authentication.

• IamAuthenticator is not a constructor

  cause This error occurs when attempting to instantiate `IamAuthenticator` incorrectly, often by importing it from the wrong module or treating it as a regular function instead of a class.
  fix Ensure `IamAuthenticator` is imported from `ibm_cloud_sdk_core.authenticators` and instantiated as a class: `from ibm_cloud_sdk_core.authenticators import IamAuthenticator` then `authenticator = IamAuthenticator(apikey='YOUR_API_KEY')`

Warnings

• breaking Major breaking changes occurred between v2.x and v3.x, including a package rename from `ibm_sdk_core` to `ibm_cloud_sdk_core`. Direct imports and configuration methods for authenticators likely require updates.
  Fix: Update package name in `pip install` and all `import` statements. Review authenticator instantiation and configuration methods as per the latest documentation.
• gotcha The library primarily serves as a foundation for other IBM Cloud SDKs. While you can directly use its authenticators, for interacting with specific IBM Cloud services (e.g., Object Storage, Watson APIs), you will typically install and use the dedicated Python SDK for that service, which in turn depends on and uses `ibm-cloud-sdk-core`.
  Fix: For service-specific interactions, identify and install the correct IBM Cloud Python SDK (e.g., `ibm-cos-sdk`, `ibm-watson`). Use `ibm-cloud-sdk-core` directly when you need advanced control over authentication or request handling for multiple services.
• gotcha Configuration for authenticators (API keys, service URLs) can be sourced from constructor arguments, environment variables (e.g., `IBMCLOUD_API_KEY`, `IBMCLOUD_AUTH_TYPE`), or configuration files. Understand the precedence rules to avoid unexpected authentication failures.
  Fix: Consult the official documentation for the precise order of precedence. Generally, constructor arguments take highest priority, followed by environment variables, then configuration files. Explicitly setting values is often the clearest approach.
• gotcha The library frequently updates its dependencies (like `requests` and `PyJWT`) to address security vulnerabilities (CVEs). Older versions of `ibm-cloud-sdk-core` might pin to vulnerable versions of these indirect dependencies.
  Fix: Regularly update `ibm-cloud-sdk-core` to the latest minor or patch version using `pip install --upgrade ibm-cloud-sdk-core` to ensure you benefit from security fixes in its dependencies.
• deprecated Older authenticator types or parameters might be deprecated in favor of new, more secure, or more flexible options. For example, `IAMAuthenticator` and `ContainerAuthenticator` have seen feature additions over time.
  Fix: Check the release notes for new authenticator features or deprecation warnings. Migrate to newer authenticator types or configurations when available to leverage new capabilities and ensure future compatibility.

Install

• pip install ibm-cloud-sdk-core Install stable version

Imports

• IAMAuthenticator

  from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

• BearerTokenAuthenticator

  from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator

• NoAuthAuthenticator

  from ibm_cloud_sdk_core.authenticators import NoAuthAuthenticator

• get_authenticator_from_external_sources
  wrong:

  from ibm_cloud_sdk_core.utils import get_authenticator_from_external_sources

  correct:

  from ibm_cloud_sdk_core.authenticators import get_authenticator_from_external_sources

  Previously this utility might have been in `utils`, but it is now correctly in `authenticators`.

Quickstart

This quickstart demonstrates how to instantiate an `IAMAuthenticator` using an API key (preferably from an environment variable) and then shows how a `BaseService` (the foundation for IBM Cloud service clients) would integrate with this authenticator. Replace `YOUR_IBMCLOUD_API_KEY` and `https://api.example.com` with actual values for your service.

import os
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
from ibm_cloud_sdk_core.base_service import BaseService

# Instantiate an authenticator using an API key from environment variables
api_key = os.environ.get('IBMCLOUD_API_KEY', 'YOUR_IBMCLOUD_API_KEY')
service_url = os.environ.get('IBMCLOUD_SERVICE_URL', 'https://api.example.com')

if api_key == 'YOUR_IBMCLOUD_API_KEY':
    print("Warning: Please set the IBMCLOUD_API_KEY environment variable or replace the placeholder.")

authenticator = IAMAuthenticator(api_key)

# Example of creating a dummy service client that uses this authenticator
class MyDummyService(BaseService):
    DEFAULT_SERVICE_URL = service_url

    def __init__(self, authenticator_instance):
        super().__init__(
            service_url=MyDummyService.DEFAULT_SERVICE_URL,
            authenticator=authenticator_instance
        )

    def do_something(self):
        # In a real SDK, this would make an API call
        print(f"Dummy service initialized with authenticator type: {type(self.authenticator).__name__}")
        print(f"Service URL: {self.service_url}")

# Initialize and use the dummy service
dummy_service = MyDummyService(authenticator)
dummy_service.do_something()