Authentication

All Camunda 8 REST API requests require authentication.

In most environments, authenticate requests by generating a JSON Web Token (JWT) and include the token in each request. In a C8Run environment, use cookie authentication.

Generate a token

SaaS

1. Create client credentials in the Clusters > Cluster name > API tab of Camunda Console.
2. Add permissions to this client for Zeebe.
3. Once you have created the client, capture the following values required to generate a token:

   Name	Environment variable name	Default value
   Client ID	ZEEBE_CLIENT_ID	-
   Client Secret	ZEEBE_CLIENT_SECRET	-
   Authorization Server URL	ZEEBE_AUTHORIZATION_SERVER_URL	https://login.cloud.camunda.io/oauth/token
   Audience	ZEEBE_TOKEN_AUDIENCE	zeebe.camunda.io
   Zeebe REST Address	ZEEBE_REST_ADDRESS	-

   caution

   When client credentials are created, the Client Secret is only shown once. Save this Client Secret somewhere safe.

4. Execute an authentication request to the token issuer:

   curl --request POST ${ZEEBE_AUTHORIZATION_SERVER_URL} \
       --header 'Content-Type: application/x-www-form-urlencoded' \
       --data-urlencode 'grant_type=client_credentials' \
       --data-urlencode "audience=${ZEEBE_TOKEN_AUDIENCE}" \
       --data-urlencode "client_id=${ZEEBE_CLIENT_ID}" \
       --data-urlencode "client_secret=${ZEEBE_CLIENT_SECRET}"
   A successful authentication response looks like the following:

   {
     "access_token": "<TOKEN>",
     "expires_in": 300,
     "refresh_expires_in": 0,
     "token_type": "Bearer",
     "not-before-policy": 0
   }
5. Capture the value of the access_token property and store it as your token.

Self-Managed

1. Add an M2M application in Identity.
2. Add permissions to this application for Camunda 8 REST API.
3. Capture the Client ID and Client Secret from the application in Identity.
4. Generate a token to access the REST API. Provide the client_id and client_secret from the values you previously captured in Identity.

   curl --location --request POST 'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode "client_id=${CLIENT_ID}" \
   --data-urlencode "client_secret=${CLIENT_SECRET}" \
   --data-urlencode 'grant_type=client_credentials'
   A successful authentication response looks like the following:

   {
     "access_token": "<TOKEN>",
     "expires_in": 300,
     "refresh_expires_in": 0,
     "token_type": "Bearer",
     "not-before-policy": 0
   }
5. Capture the value of the access_token property and store it as your token.

Use a token

Include the previously captured token as an authorization header in each request: Authorization: Bearer <TOKEN>.

For example, to send a request to the Camunda 8 REST API's /topology endpoint:

SaaS

tip

The ${ZEEBE_REST_ADDRESS} variable below represents the URL of the Camunda 8 REST API. You can capture this URL when creating an API client. You can also construct it as https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/.

Self-Managed

tip

The ${ZEEBE_REST_ADDRESS} variable below represents the URL of the Camunda 8 REST API. You can configure this value in your Self-Managed installation. The default value is http://localhost:8080/.

curl --header "Authorization: Bearer ${TOKEN}" \
     ${ZEEBE_REST_ADDRESS}/v2/topology

A successful response includes information about the cluster. For example:

{
  "brokers": [
    ...
  ],
  "clusterSize": 3,
  "partitionsCount": 3,
  "replicationFactor": 3,
  "gatewayVersion": "8.6.0"
}

Token expiration

Access tokens expire according to the expires_in property of a successful authentication response. After this duration, in seconds, you must request a new access token.

Authentication via cookie (C8Run only)

Cookie authentication is required to access the Camunda 8 REST API in a C8Run environment. The cookie can be obtained by using the API endpoint /api/login. Take the following steps:

1. Log in as user 'demo' and store the cookie in the file cookie.txt:

curl --request POST 'http://localhost:8080/api/login?username=demo&password=demo' \
  --cookie-jar cookie.txt

2. Send the cookie (as a header) in each API request. In this case, request all process instances:

curl --request GET 'http://localhost:8080/v2/topology'  \
  --cookie cookie.txt \
  --header 'Content-Type: application/json'

Authentication via cookie with the Java client

To access Camunda APIs in a Camunda 8 Run environment with the Java client, you'll need to manually retrieve and send a cookie.