Skip to main content
Version: 8.8 (unreleased)

This page describes the available authentication methods for accessing the Orchestration Cluster REST API. It outlines when to use each method and how to configure your API requests for secure and appropriate access.

Authentication methods for the Orchestration Cluster REST API

The Orchestration Cluster REST API supports three authentication methods depending on your environment and configuration:

  • No Authentication
  • Basic Authentication
  • OIDC Access Token Authentication

When to use each method​

  • No Authentication: Use for local development only, with C8 Run or Docker Compose, when security is not required. Not recommended for production.
  • Basic Authentication: Use for simple username/password protection, typically in C8 Run with authentication enabled.
  • OIDC Access Token Authentication: Use for production, SaaS, or any environment where secure, standards-based authentication is required. Required for SaaS and recommended for Self-Managed clusters in production.

Authentication support matrix​

DistributionDefault AuthenticationSupports No AuthSupports Basic AuthSupports OIDC Access Token
C8 RunNone✅ (default)✅ (when enabled)✅ (when configured)
Docker ComposeNone✅ (default)✅ (when enabled)✅ (when configured)
HelmBasic Auth✅ (when Auth disabled)✅ (default)✅ (when configured)
SaaSOIDC Access Token❌❌✅ (required)

Authenticate API calls

No Authentication (Local Development)​

By default, Camunda 8 Run and Docker Compose expose the Orchestration Cluster REST API without authentication for local development. You can make API requests directly:

curl http://localhost:8080/v2/topology

Basic Authentication​

Enable Basic Auth in C8 Run by configuring authentication in your application.yaml. For detailed steps, see the C8 Run documentation on enabling authentication.

On Helm, Basic Auth is enabled by default for the Orchestration Cluster REST API.

Once authentication is enabled, you can use Basic Authentication with your username and password. Make sure a user is created for this purpose, or use the default user: demo/demo. Include your username and password in each API request:

curl --user username:password \
     http://localhost:8080/v2/topology
note

Basic Authentication only supports a very small number of API requests per second, and may not be suitable for production use. Please see Camunda components troubleshooting

OIDC Access Token Authentication using Client Credentials​

OIDC Access Token Authentication is the recommended method for production and required for SaaS. You must obtain an Access Token and pass it as an OAuth 2.0 Bearer Token it in the Authorization header of each request.

  1. Create client credentials in the Camunda Console.
  2. Use the credentials to request an Access Token:
curl --request POST ${CAMUNDA_OAUTH_URL} \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode "audience=${CAMUNDA_TOKEN_AUDIENCE}" \
    --data-urlencode "client_id=${CAMUNDA_CLIENT_ID}" \
    --data-urlencode "client_secret=${CAMUNDA_CLIENT_SECRET}"
  1. Use the access_token from the response in your API requests:
curl --header "Authorization: Bearer ${TOKEN}" \
     ${BASE_URL}/topology

Replace the ${BASE_URL} based on the address of your cluster. See the Context paths for SaaS URL formats.

OIDC Access Token Authentication using X.509 Client Certificates​

For advanced security scenarios, you can use OIDC Access Tokens from your IdP obtained using X.509 Client Certificates. This is typically required in Self-Managed environments where mutual TLS (mTLS) is enforced by your identity provider (such as Keycloak).

  • The Java client supports OIDC Access Token retrieval using X.509 Client Certificates out of the box. You can configure the necessary keystore and truststore settings either via code or environment variables. See Java client authentication for a full example and configuration details.
  • For other clients or custom integrations, refer to your identity provider's documentation for how to obtain tokens using X.509 certificates.

Token management in clients​

When using official clients such as the Java client or Spring SDK, token acquisition and renewal are handled automatically. You do not need to manually obtain or refresh tokens as these clients will request and refresh tokens as needed based on your configuration.