camunda-orchestration-sdk 8.9.0.dev4

Python client for Camunda 8 Orchestration Cluster API

Camunda Orchestration Cluster API – Python SDK

Installing the SDK to your project

Stable release (recommended for production)

The stable version tracks the latest supported Camunda server release. The first stable release will be 8.9.0.

pip install camunda-orchestration-sdk

Pre-release / dev channel

Pre-release versions (e.g. 8.9.0.dev2) are published from the main branch and contain the latest changes targeting the next server minor version. Use these to preview upcoming features or validate your integration ahead of a stable release.

# pip
pip install --pre camunda-orchestration-sdk

# pin to a specific pre-release
pip install camunda-orchestration-sdk==8.9.0.dev2

In a requirements.txt:

camunda-orchestration-sdk>=8.9.0.dev1

Note: Pre-release versions may contain breaking changes between builds. Pin to a specific version if you need reproducible builds.

Using the generated SDK

The generated SDK provides two convenience clients:

• CamundaClient: sync-only convenience client.
• CamundaAsyncClient: async-only convenience client.

Quick start (Zero-config – recommended)

Keep configuration out of application code. Let the client read CAMUNDA_* variables from the environment (12-factor style). This makes secret rotation, environment promotion (dev → staging → prod), and operational tooling (vaults / secret managers) safer and simpler.

If no configuration is present, the SDK defaults to a local Camunda 8 Run-style endpoint at http://localhost:8080/v2.

from camunda_orchestration_sdk import CamundaClient, CamundaAsyncClient

# Zero-config construction: reads CAMUNDA_* from the environment
client = CamundaClient()
async_client = CamundaAsyncClient()

Typical .env (example):

CAMUNDA_REST_ADDRESS=https://cluster.example/v2
CAMUNDA_AUTH_STRATEGY=OAUTH
CAMUNDA_CLIENT_ID=***
CAMUNDA_CLIENT_SECRET=***

Advanced: Programmatic configuration (use sparingly)

Only use configuration={...} when you must supply or mutate configuration dynamically (e.g. tests, multi-tenant routing, or ephemeral preview environments). Keys mirror their CAMUNDA_* environment names.

from camunda_orchestration_sdk import CamundaClient

client = CamundaClient(
    configuration={
        "CAMUNDA_REST_ADDRESS": "http://localhost:8080/v2",
        "CAMUNDA_AUTH_STRATEGY": "NONE",
    }
)

Loading configuration from a .env file (CAMUNDA_LOAD_ENVFILE)

The SDK can optionally load configuration values from a dotenv file.

• Set CAMUNDA_LOAD_ENVFILE=true (or 1 / yes) to load .env from the current working directory.
• Set CAMUNDA_LOAD_ENVFILE=/path/to/file.env to load from an explicit path.
• If the file does not exist, it is silently ignored.
• Precedence is: .env < environment variables < explicit configuration={...} passed to the client.
• The resolver reads dotenv values without mutating os.environ.

Example .env:

CAMUNDA_REST_ADDRESS=http://localhost:8080/v2
CAMUNDA_CLIENT_ID=your-client-id
CAMUNDA_CLIENT_SECRET=your-client-secret

Enable loading from the current directory:

export CAMUNDA_LOAD_ENVFILE=true
python your_script.py

Or enable loading from a specific file:

export CAMUNDA_LOAD_ENVFILE=~/camunda/dev.env
python your_script.py

You can also enable it via the explicit configuration dict:

from camunda_orchestration_sdk import CamundaClient

client = CamundaClient(configuration={"CAMUNDA_LOAD_ENVFILE": "true"})

Authentication

The SDK supports three authentication strategies, controlled by CAMUNDA_AUTH_STRATEGY:

Strategy	When to use
NONE	Local development with unauthenticated Camunda (default)
OAUTH	Camunda SaaS or any OAuth 2.0 Client Credentials endpoint
BASIC	Self-Managed Camunda with Basic auth (username/password)

Auto-detection

If you omit CAMUNDA_AUTH_STRATEGY, the SDK infers it from the credentials you provide:

• Only CAMUNDA_CLIENT_ID + CAMUNDA_CLIENT_SECRET → OAUTH
• Only CAMUNDA_BASIC_AUTH_USERNAME + CAMUNDA_BASIC_AUTH_PASSWORD → BASIC
• No credentials → NONE
• Both OAuth and Basic credentials present → error (set CAMUNDA_AUTH_STRATEGY explicitly)

OAuth 2.0

CAMUNDA_REST_ADDRESS=https://cluster.example/v2
CAMUNDA_AUTH_STRATEGY=OAUTH
CAMUNDA_CLIENT_ID=your-client-id
CAMUNDA_CLIENT_SECRET=your-client-secret
# Optional:
# CAMUNDA_OAUTH_URL=https://login.cloud.camunda.io/oauth/token
# CAMUNDA_TOKEN_AUDIENCE=zeebe.camunda.io

Basic authentication

CAMUNDA_REST_ADDRESS=http://localhost:8080/v2
CAMUNDA_AUTH_STRATEGY=BASIC
CAMUNDA_BASIC_AUTH_USERNAME=your-username
CAMUNDA_BASIC_AUTH_PASSWORD=your-password

Or programmatically:

from camunda_orchestration_sdk import CamundaClient

client = CamundaClient(
    configuration={
        "CAMUNDA_REST_ADDRESS": "http://localhost:8080/v2",
        "CAMUNDA_AUTH_STRATEGY": "BASIC",
        "CAMUNDA_BASIC_AUTH_USERNAME": "your-username",
        "CAMUNDA_BASIC_AUTH_PASSWORD": "your-password",
    }
)

Configuration reference

All CAMUNDA_* environment variables recognised by the SDK. These can also be passed as keys in the configuration={...} dict.

Variable	Default	Description
ZEEBE_REST_ADDRESS	http://localhost:8080/v2	REST API base URL (alias for CAMUNDA_REST_ADDRESS).
CAMUNDA_REST_ADDRESS	http://localhost:8080/v2	REST API base URL. /v2 is appended automatically if missing.
CAMUNDA_TOKEN_AUDIENCE	zeebe.camunda.io	OAuth token audience.
CAMUNDA_OAUTH_URL	https://login.cloud.camunda.io/oauth/token	OAuth token endpoint URL.
CAMUNDA_CLIENT_ID	—	OAuth client ID.
CAMUNDA_CLIENT_SECRET	—	OAuth client secret.
CAMUNDA_CLIENT_AUTH_CLIENTID	—	Alias for CAMUNDA_CLIENT_ID.
CAMUNDA_CLIENT_AUTH_CLIENTSECRET	—	Alias for CAMUNDA_CLIENT_SECRET.
CAMUNDA_AUTH_STRATEGY	NONE	Authentication strategy: NONE, OAUTH, or BASIC. Auto-inferred from credentials if omitted.
CAMUNDA_BASIC_AUTH_USERNAME	—	Basic auth username. Required when CAMUNDA_AUTH_STRATEGY=BASIC.
CAMUNDA_BASIC_AUTH_PASSWORD	—	Basic auth password. Required when CAMUNDA_AUTH_STRATEGY=BASIC.
CAMUNDA_SDK_LOG_LEVEL	error	SDK log level: silent, error, warn, info, debug, trace, or silly.
CAMUNDA_TOKEN_CACHE_DIR	—	Directory for OAuth token disk cache. Disabled if unset.
CAMUNDA_TOKEN_DISK_CACHE_DISABLE	false	Disable OAuth token disk caching.
CAMUNDA_LOAD_ENVFILE	—	Load configuration from a .env file. Set to true (or a file path).

Synchronous Usage

from camunda_orchestration_sdk import CamundaClient

# Configure via environment (recommended): CAMUNDA_REST_ADDRESS / auth vars
with CamundaClient() as client:
    topology = client.get_topology()
    print(topology)

Asynchronous Usage

import asyncio
from camunda_orchestration_sdk import CamundaAsyncClient

async def main():
    # Configure via environment (recommended): CAMUNDA_REST_ADDRESS / auth vars
    async with CamundaAsyncClient() as client:
        topology = await client.get_topology()
        print(topology)

asyncio.run(main())

Logging

The SDK uses loguru for logging. You can control the log level by setting the LOGURU_LEVEL environment variable.

# Run with INFO level (default is DEBUG)
LOGURU_LEVEL=INFO python your_script.py

# Run with WARNING level
LOGURU_LEVEL=WARNING python your_script.py

# Run with TRACE level (more verbose than DEBUG)
LOGURU_LEVEL=TRACE python your_script.py

License

Apache-2.0