Skip to main content
Version: 8.8

Java client

The Camunda Java Client is the official Java library for building process applications that integrate with Camunda 8. Whether you are orchestrating microservices, managing human tasks, or visualizing process data, this client provides everything needed to interact with the Orchestration Cluster programmatically.

Public API

The Camunda Java Client is part of the Camunda 8 public API and follows Semantic Versioning (except for alpha features). Minor and patch releases will not introduce breaking changes.

What is the Camunda Java Client?​

The Camunda Java Client is a comprehensive library enabling Java developers to:

  • Deploy processes and decisions to Camunda 8 clusters
  • Start and manage processes programmatically
  • Implement job workers to handle automated tasks within your processes
  • Query and manage process data via the Orchestration Cluster API

It supports both REST and gRPC protocols, authentication setup, and provides robust error handling with retry mechanisms.

Migration from Zeebe Java Client

The Camunda Java Client replaces the Zeebe Java Client as of version 8.8.

  • Provides improved structure and full Orchestration Cluster API support
  • Uses REST as default communication protocol (gRPC configurable)
  • The Zeebe Java Client will be removed in version 8.10
  • Migrate before upgrading to 8.10 to avoid breaking changes

See our migration guide for details.

What can you build with it?​

Use the Camunda Java Client to build:

  • Job workers that perform automated tasks and call external systems (APIs, databases, file systems)
  • Integration services that connect Camunda processes with existing systems or third-party services
  • Data processing applications that leverage process data for visualization, analytics, or business intelligence

Get started​

Step 1: Add the dependency​

Add the Camunda Java Client to your project:

Maven:

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>camunda-client-java</artifactId>
  <version>${camunda.version}</version>
</dependency>

Gradle:

implementation 'io.camunda:camunda-client-java:${camunda.version}'

Use the latest version from Maven Central.

Step 2a: Connect to a Self-Managed Orchestration Cluster​

Create a client instance to connect to your Self-Managed Camunda 8 cluster.
Select the appropriate authentication method for your environment:

Use for: Local development when security is not required.

private static final String CAMUNDA_GRPC_ADDRESS = "[Address of Zeebe API (gRPC) - default: http://localhost:26500]";
private static final String CAMUNDA_REST_ADDRESS = "[Address of the Orchestration Cluster API - default: http://localhost:8080]";

public static void main(String[] args) {

    try (CamundaClient client = CamundaClient.newClientBuilder()
            .grpcAddress(URI.create(CAMUNDA_GRPC_ADDRESS))
            .restAddress(URI.create(CAMUNDA_REST_ADDRESS))
            .build()) {

        // Test the connection
        client.newTopologyRequest().send().join();
        System.out.println("Connected to Camunda 8!");
    }
}

What this code does

  1. Creates a no-authentication provider – Configures the client to skip authentication.
  2. Builds a client using the protocol-specified transport – Uses plaintext or TLS depending on whether the addresses use http or https.
  3. Connects to both APIs – Configures access to the Zeebe gRPC and Orchestration Cluster REST APIs.
  4. Tests the connection – Verifies connectivity by requesting cluster topology information.

Environment variables option
You can also configure the client using environment variables:

export CAMUNDA_GRPC_ADDRESS='[Address of Zeebe API (gRPC) - default: http://localhost:26500]'
export CAMUNDA_REST_ADDRESS='[Address of the Orchestration Cluster API - default: http://localhost:8080]'
CamundaClient client = CamundaClient.newClientBuilder().build();

The client will automatically read these environment variables and configure the appropriate authentication method.

Ensure addresses are in absolute URI format: scheme://host(:port). The protocol (http or https) determines whether the connection is encrypted.

Step 2b: Configure the Orchestration Cluster connection for SaaS​

Use for: Camunda 8 SaaS environments. Get the values below from your Camunda Console client credentials.

private static final String CAMUNDA_CLUSTER_ID = "[Cluster ID from Console]";
private static final String CAMUNDA_CLIENT_ID = "[Client ID from Console]";
private static final String CAMUNDA_CLIENT_SECRET = "[Client Secret from Console]";
private static final String CAMUNDA_CLUSTER_REGION = "[Cluster Region from Console]";

public static void main(String[] args) {

    try (CamundaClient client = CamundaClient.newCloudClientBuilder()
            .withClusterId(CAMUNDA_CLUSTER_ID)
            .withClientId(CAMUNDA_CLIENT_ID)
            .withClientSecret(CAMUNDA_CLIENT_SECRET)
            .withRegion(CAMUNDA_CLUSTER_REGION)
            .build()) {

        // Test the connection
        client.newTopologyRequest().send().join();
        System.out.println("Connected to Camunda 8!");
    }
}

What this code does

  1. Sets up SaaS authentication – Configures the client to connect to Camunda 8 SaaS using your cluster credentials.
  2. Builds a cloud client – Creates a client optimized for SaaS with automatic endpoint discovery.
  3. Connects to your cluster – Uses your cluster ID and region to locate and connect to the correct SaaS instance.
  4. Tests the connection – Verifies SaaS authentication by requesting cluster topology information.

Environment variables option
You can also set connection details via environment variables to create the client more simply:

export CAMUNDA_GRPC_ADDRESS='[Orchestration Cluster gRPC Address from Console]'
export CAMUNDA_REST_ADDRESS='[Orchestration Cluster REST Address from Console]'
export CAMUNDA_OAUTH_URL='[OAuth URL from Console]'
export CAMUNDA_TOKEN_AUDIENCE='[Audience from Console - default: zeebe.camunda.io]'
export CAMUNDA_CLIENT_ID='[Client ID from Console]'
export CAMUNDA_CLIENT_SECRET='[Client Secret from Console]'
CamundaClient client = CamundaClient.newClientBuilder().build();

The client will automatically read the environment variables and configure the appropriate authentication method.

note

Ensure addresses are in absolute URI format: scheme://host(:port).

Step 3: Start building your process application​

With a connected client, you are ready to build your process application. Below are the core operations you’ll typically perform, along with guidance on the next steps.

Essential operations​

Deploy a process:

final DeploymentEvent deploymentEvent = client.newDeployResourceCommand()
    .addResourceFromClasspath("process.bpmn")
    .send()
    .join();

This deploys your BPMN process definition to the cluster. Place your .bpmn files in src/main/resources and reference them by filename.

Start a process instance:

final ProcessInstanceEvent processInstanceEvent = client.newCreateInstanceCommand()
    .bpmnProcessId("my-process")
    .latestVersion()
    .variables(Map.of("orderId", "12345", "amount", 100.0))
    .send()
    .join();

This creates a new instance of your process. The bpmnProcessId should match the Process ID from your BPMN file, and you can pass initial variables as a Map.

For a comprehensive example demonstrating these steps, see the DeployAndComplete example in the Camunda 8 examples repository. This example illustrates a complete workflow from process deployment to job completion.

Key features and capabilities​

  • Full Orchestration Cluster 8 API support: Access all Orchestration Cluster API capabilities, including process deployment, management, job handling, and querying process data.
  • Multiple authentication methods: Supports no authentication (development), basic authentication, and OIDC access tokens for production environments.
  • Automatic token management: Handles authentication token acquisition and renewal automatically—no manual token management required.
  • Protocol flexibility: Choose between REST and gRPC protocols depending on your requirements and infrastructure.

Next steps and resources​

Learn the fundamentals

Advanced topics

Need help?