> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-solutions-factory/use-hsf/plugins/harness-platform-sdk.md).

# Harness Platform SDK

Install, configure, and use the Harness Platform SDK, a production-grade Python SDK for the Harness platform API.

The Harness Platform SDK is a production-grade Python SDK for the Harness platform API. It is built with Pydantic v2 and httpx, and it ships with a test suite. Typed wrappers cover Next-Gen (Core), Pipelines, Authorization, Infrastructure as Code, and Internal Developer Portal, so Python tools can call Harness without repeated Bash or curl scripts.

Version 1.0.0 is synchronous only. Async support is planned for a later release.

***

## What you will learn from this topic

* **Install options:** How to install the SDK from PyPI, Docker, or a local checkout.
* **Client setup:** How `HarnessClient` takes an API key, account ID, and default org and project.
* **Resource coverage:** Which platform domains and resources the typed wrappers include.
* **Errors and scope:** How authentication failures, API errors, and missing scope are reported.

***

## Before you begin

Confirm the following before you install the SDK:

* **Python 3.11 or later:** The package is tested on Python 3.11, 3.12, and 3.14.
* **Harness API credentials:** You need an API key and the account ID the client will call. Go to [RBAC in Harness](https://developer.harness.io/docs/platform/role-based-access-control/rbac-in-harness) to confirm the key's role can call the resources you use.
* **Network access to Harness:** The client calls `https://app.harness.io` unless you set another base URL.

{% hint style="warning" %}
**Package rename**

`harness-platform-sdk` 1.0.0 replaces `harness-python-sdk`. An upgrade from `harness-python-sdk` 0.13.0 is a breaking change. Install the new package name and import `harness_platform_sdk`.
{% endhint %}

***

## Use the SDK

Install the package, create a client, and use the tables and examples below for modules, errors, scope, and tests.

### Package notes

These constraints apply to the 1.0.0 release:

* **Python:** 3.11 or later.
* **License:** Business Source License 1.1 (BUSL-1.1).
* **Concurrency:** Synchronous calls only. Async support is not in this version.

### Install the SDK

Install from PyPI for local development. Use the image when you want a fixed runtime, or install from source when you are changing the SDK.

{% tabs %}
{% tab title="PyPI" %}

```bash
pip install harness-platform-sdk
```

{% endtab %}

{% tab title="Docker" %}

```bash
docker pull harnesssolutionfactory/harness-platform-sdk:1.0.0
docker run --rm harnesssolutionfactory/harness-platform-sdk:1.0.0 -c \
  "from harness_platform_sdk import HarnessClient; print('Ready')"
```

{% endtab %}

{% tab title="Source" %}

```bash
git clone https://github.com/harness/harness-platform-sdk.git
cd harness-platform-sdk
pip install -e .
```

{% endtab %}
{% endtabs %}

### Create a client

Construct `HarnessClient` with an API key, account ID, and optional default org and project. Use the client as a context manager so the HTTP client closes when the block ends.

```python
from harness_platform_sdk import HarnessClient

# Create a client
client = HarnessClient(
    api_key="your-api-key",
    account_id="your-account-id",
    default_org="your-org",
    default_project="your-project"
)

# Use context manager for automatic cleanup
with client:
    # Access resource APIs
    orgs = client.organizations.list()
    for org in orgs:
        print(f"Organization: {org.identifier}")
```

### Core modules

These types are the entry points for configuration, calls, and failures:

| Module              | Description                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HarnessClient`     | Main entry point for all API interactions. Handles HTTP methods with built-in retry (429, 503), scope resolution (account/org/project), URL template substitution, and pagination. |
| `HarnessConfig`     | Configuration management: API key, account ID, base URL, timeout, retry settings, and SSL verification control.                                                                    |
| `Scope`             | Frozen Pydantic model representing request context. Requires account ID; org and project are optional.                                                                             |
| `PaginationStyle`   | Enum for pagination type: `OFFSET` (pageIndex/pageSize) or `CURSOR` (nextPageToken).                                                                                               |
| Exception hierarchy | `HarnessSdkError` (base), `ScopeNotSetError` (missing required scope fields), `ApiError` (non-2xx responses, with status/body/headers), `AuthError` (401/403 responses).           |

### Resource APIs

Typed wrappers are grouped by platform domain:

| Domain                    | Resources                                                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Next-Gen (Core)           | Organizations, Projects, Services, Service Overrides, Connectors, Secrets, Infrastructures, Variables, User Groups, Environments V2 |
| Pipeline                  | Pipelines (v0), Input Sets (v0), Triggers (v0), Templates (v0)                                                                      |
| Authorization             | Roles, Resource Groups, Role Assignments                                                                                            |
| Infrastructure as Code    | Workspaces, Workspace Approvals, Workspace States, Workspace Variables, Workspace Default Pipelines                                 |
| Internal Developer Portal | Entities, Catalog Custom Properties, Scores                                                                                         |

### Design principles

The client follows six rules:

1. **Single entry point:** All domain APIs are accessed through `HarnessClient`.
2. **Scope resolution:** The client merges call-time scope with the default scope.
3. **Type safety:** Request and response models are Pydantic v2 models with validation.
4. **Error handling:** Failures raise explicit exception types with actionable messages.
5. **Retry logic:** Transient failures retry with exponential backoff.
6. **No async:** Calls are synchronous through httpx. Async support is deferred to a later version.

### Configure the client

Pass keyword arguments for a short setup, or build a `HarnessConfig` when you need timeouts, retries, or a non-default base URL.

```python
from harness_platform_sdk import HarnessClient, HarnessConfig

# Option 1: Keyword arguments
client = HarnessClient(
    api_key="key",
    account_id="acc",
    default_org="my-org"
)

# Option 2: Explicit config
config = HarnessConfig(
    api_key="key",
    account_id="acc",
    base_url="https://app.harness.io",
    timeout=30.0,
    max_retries=3,
    retry_status_codes=[429, 503],
    retry_enabled=True,
    verify_ssl=True
)
client = HarnessClient(config=config)
```

### Handle API errors

Catch `AuthError` for 401 and 403 responses, and `ApiError` for other non-2xx responses. Call `close()` when you do not use the context manager.

```python
from harness_platform_sdk import HarnessClient, AuthError, ApiError

client = HarnessClient(api_key="key", account_id="acc")

try:
    result = client.organizations.list()
except AuthError as e:
    print(f"Auth failed: {e.status_code}")
    # Handle 401/403
except ApiError as e:
    print(f"API error: {e.status_code}")
    # Handle other non-2xx
finally:
    client.close()
```

### Set request scope

Set the default org and project on the client, then replace that default later with `set_default_scope`. Account ID is required. Org and project are optional.

```python
from harness_platform_sdk import HarnessClient, Scope

# Set default scope at construction
client = HarnessClient(
    api_key="key",
    account_id="acc",
    default_org="org-1",
    default_project="proj-1"
)

# Update default scope
client.set_default_scope(org="org-2", project="proj-2")
```

`Scope` is the frozen model the client uses for that context. Construct a client as shown above. You do not need to build a `Scope` yourself for the default path.

### Run tests

From a source checkout, run the suite with mise or pytest:

```bash
# Run all tests
mise run tests

# Run with coverage report
mise run tests:cov

# Run specific test file
pytest tests/unit_tests/test_client.py -v
```

CI enforces a coverage target of at least 85 percent.

### Version and support

Release 1.0.0 is the current production version. Use these links for license terms, source, and issues:

* **Current version:** 1.0.0 (Production Ready)
* **License:** Business Source License 1.1 (BUSL-1.1). Go to the [License](https://github.com/harness/harness-platform-sdk/blob/main/License) file to read the terms.
* **Repository:** [harness/harness-platform-sdk](https://github.com/harness/harness-platform-sdk)
* **Contributing:** Go to [CONTRIBUTING.md](https://github.com/harness/harness-platform-sdk/blob/main/CONTRIBUTING.md) to submit a change.
* **Issues and feature requests:** [GitHub Issues](https://github.com/harness/harness-platform-sdk/issues)

***

## Troubleshooting

### Import fails after upgrading from `harness-python-sdk`

1.0.0 does not keep the old package name. Uninstall `harness-python-sdk`, run `pip install harness-platform-sdk`, and change imports to `from harness_platform_sdk import ...`.

### `AuthError` on the first API call

`AuthError` means the platform returned 401 or 403. Confirm `api_key` and `account_id` on the client, and confirm the key's role includes the resource you called. The `status_code` attribute on the exception is the HTTP status.

### `ScopeNotSetError` before a request is sent

`ScopeNotSetError` means a required scope field is missing. Every client needs `account_id`. Set it in the `HarnessClient` constructor or on `HarnessConfig`. Org and project stay optional unless the resource you call requires them.

### Calls fail on Python older than 3.11

The package requires Python 3.11 or later. Check `python --version` and recreate the virtual environment with a supported interpreter before you install again.

***

## Next steps

You can install the SDK and call platform resources through `HarnessClient`.

* [Plugin overview](/harness-solutions-factory/use-hsf/plugins/overview.md): Compare the other HSF plugin images and versions.
* [IDP Resource Manager plugin](/harness-solutions-factory/use-hsf/plugins/harness-idp-resource-manager.md): Use the plugin that manages Internal Developer Portal resources from a pipeline.
* [harness-platform-sdk repository](https://github.com/harness/harness-platform-sdk): Read the source, tests, and changelog.

{% @harness-feedback/feedback %}