chore(sdk): add support for custom auth endpoint and add example (#1272)

Author: rubenhoenle

CHANGELOG.md

@@ -1,4 +1,6 @@
 ## Release (2025-XX-YY)
+- `core`: [v0.2.0](core/CHANGELOG.md#v020-2025-06-12)
+  - **Feature:** Allow setting custom token endpoint url in configuration
 - `iaas`: [v0.5.3](services/iaas/CHANGELOG.md#v053-2025-06-12)
   - Increase max length of description from 127 to 255 for 
     - Security groups: `BaseSecurityGroupRule`, `CreateSecurityGroupPayload`, `CreateSecurityGroupRulePayload`, `SecurityGroup`, `SecurityGroupRule`, `UpdateSecurityGroupPayload`

README.md

@@ -3,7 +3,8 @@
 [![CD Workflow](https://github.com/stackitcloud/stackit-sdk-python/actions/workflows/cd.yaml/badge.svg)](https://github.com/stackitcloud/stackit-sdk-python/actions/workflows/cd.yaml)
 [![Dependency-Updater](https://github.com/stackitcloud/stackit-sdk-python/actions/workflows/dependency-checker.yaml/badge.svg)](https://github.com/stackitcloud/stackit-sdk-python/actions/workflows/dependency-checker.yaml)
 
-> ⓘ INFO: The STACKIT Python SDK is in beta and in active development.
+> [!NOTE]
+> The STACKIT Python SDK is in beta and in active development.
 
 # Overview
 
@@ -154,6 +155,29 @@ Using this flow is less secure since the token is long-lived. You can provide th
 2. Setting the environment variable `STACKIT_SERVICE_ACCOUNT_TOKEN`
 3. Setting it in the credentials file (see above)
 
+## Using custom endpoints
+
+The example below shows how to use the STACKIT Python SDK in custom STACKIT environments.
+
+```python
+from stackit.iaas.api.default_api import DefaultApi
+from stackit.core.configuration import Configuration
+
+project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+
+# Create a new API client that uses custom authentication and service endpoints
+config = Configuration(
+    service_account_key_path="/home/bob/.stackit/sa_key.json",
+    custom_token_endpoint="https://service-account.api.stackit.cloud/token",
+    custom_endpoint="https://iaas.api.eu01.stackit.cloud",
+)
+client = DefaultApi(config)
+
+print(client.list_project_nics(
+    project_id=project_id,
+))
+```
+
 ## Reporting issues
 
 If you encounter any issues or have suggestions for improvements, please open an issue in the repository or create a ticket in the [STACKIT Help Center](https://support.stackit.cloud/).

core/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.2.0 (2025-06-12)
+- **Feature:** Allow setting custom token endpoint url in configuration
+
 ## v0.1.0 (2024-12-04)
 
 - The core module offers functionality, such as authorization and configuration, to be used together with the Python SDK service modules

core/pyproject.toml

@@ -3,7 +3,7 @@ name = "stackit-core"
 
 [tool.poetry]
 name = "stackit-core"
-version = "v0.1.0"
+version = "v0.2.0"
 authors = ["STACKIT Developer Tools <developer-tools@stackit.cloud>"]
 description = "Core functionality for the STACKIT SDK for Python"
 readme = "README.md"

core/src/stackit/core/configuration.py

@@ -32,13 +32,14 @@ def __init__(
         private_key_path=None,
         credentials_file_path=None,
         custom_endpoint=None,
+        custom_token_endpoint=None,
         custom_http_session=None,
         custom_auth=None,
         server_index=None,
     ) -> None:
         environment_variables = EnvironmentVariables()
         self.region = region if region else environment_variables.region
-        self.token_endpoint = environment_variables.token_baseurl
+        self.token_endpoint = custom_token_endpoint if custom_token_endpoint else environment_variables.token_baseurl
         self.service_account_token = (
             environment_variables.service_account_token if service_account_token is None else service_account_token
         )