Authentication
All Tasklist API requests require authentication. To authenticate, generate a JSON Web Token (JWT) and include it in each request.
Generate a token
- SaaS
- Self-Managed
- Create client credentials in the Clusters > Cluster name > API tab of Camunda Console.
- Add permissions to this client for Tasklist.
- 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
Tasklist REST Address CAMUNDA_TASKLIST_BASE_URL
- cautionWhen client credentials are created, the
Client Secret
is only shown once. Save thisClient Secret
somewhere safe. - Execute an authentication request to the token issuer:
A successful authentication response looks like the following:
curl --request POST ${ZEEBE_AUTHORIZATION_SERVER_URL} \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=tasklist.camunda.io' \
--data-urlencode "client_id=${ZEEBE_CLIENT_ID}" \
--data-urlencode "client_secret=${ZEEBE_CLIENT_SECRET}"{
"access_token": "<TOKEN>",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0
} - Capture the value of the
access_token
property and store it as your token.
- Add an M2M application in Identity.
- Add permissions to this application for Tasklist API.
- Capture the
Client ID
andClient Secret
from the application in Identity. - Generate a token to access the REST API. Provide the
client_id
andclient_secret
from the values you previously captured in Identity.A successful authentication response looks like the following: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'{
"access_token": "<TOKEN>",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0
} - Capture the value of the
access_token
property and store it as your token.
See the Tasklist Configuration - Authentication documentation for more information about this authentication method.
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 Tasklist API's "Search tasks" endpoint:
- SaaS
- Self-Managed
The ${CAMUNDA_TASKLIST_BASE_URL}
variable below represents the URL of the Tasklist API. You can capture this URL when creating an API client. You can also construct it as https://${REGION}.tasklist.camunda.io/${CLUSTER_ID}
.
The ${CAMUNDA_TASKLIST_BASE_URL}
variable below represents the URL of the Tasklist API. You can configure this value in your Self-Managed installation. The default value is http://localhost:8082
.
curl --request POST ${CAMUNDA_TASKLIST_BASE_URL}/v1/tasks/search \
--header "Authorization: Bearer ${TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{}'
A successful response includes matching tasks. For example:
[
{
"id": "12345",
"name": "Do something",
...
}
]
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 (Self-Managed only)
When authenticating via cookie, note that Cross-Site Request Forgery (CSRF) protection must be disabled to allow this method of authentication. In a Camunda Self-Managed cluster, set the configuration property camunda.tasklist.csrfPreventionEnabled
to false
.
Another way to access the Tasklist API in a Self-Managed cluster is to send cookie headers in each request. This works for scenarios where authentication is managed by Tasklist and not by Identity. The cookie can be obtained by using the API endpoint /api/login
:
Example:
- 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
- Send the cookie as a header in each API request. In this case, request all process definitions.
curl --request POST 'http://localhost:8080/v1/process-definitions/search' \
--cookie cookie.txt \
--header 'Content-Type: application/json' -d '{}'