Authentication

All Web Modeler API requests require authentication. To authenticate, generate a JSON Web Token (JWT) depending on your environment and include it in each request.

note

Clients using a valid generated token have access to all resources within an organization, similar to super-user mode.

While there's no project-level access control enforced in the API, access is still dependent on the CRUD operations assigned.

Generate a token

SaaS

1. Create client credentials by clicking Console > Organization > Administration API > Create new credentials.
2. Add permissions to this client for Web Modeler API with the needed CRUD permissions.
3. Once you have created the client, capture the following values required to generate a token:

   Name	Environment variable name	Default value
   Client ID	CAMUNDA_CONSOLE_CLIENT_ID	-
   Client Secret	CAMUNDA_CONSOLE_CLIENT_SECRET	-
   Authorization Server URL	CAMUNDA_OAUTH_URL	https://login.cloud.camunda.io/oauth/token
   Audience	CAMUNDA_CONSOLE_OAUTH_AUDIENCE	api.cloud.camunda.io

   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 ${CAMUNDA_OAUTH_URL} \
       --header 'Content-Type: application/x-www-form-urlencoded' \
       --data-urlencode 'grant_type=client_credentials' \
       --data-urlencode "audience=${CAMUNDA_CONSOLE_OAUTH_AUDIENCE}" \
       --data-urlencode "client_id=${CAMUNDA_CONSOLE_CLIENT_ID}" \
       --data-urlencode "client_secret=${CAMUNDA_CONSOLE_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 Web Modeler API with the needed CRUD permissions.
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 Web Modeler API's /info endpoint:

SaaS

curl --header "Authorization: Bearer ${TOKEN}" \
     https://modeler.cloud.camunda.io/api/v1/info

Self-Managed

tip

The ${WEB_MODELER_REST_URL} variable below represents the URL of the Web Modeler API. You can configure this value in your Self-Managed installation. The default value is http://localhost:8070.

curl --header "Authorization: Bearer ${TOKEN}" \
     ${WEB_MODELER_REST_URL}/api/v1/info

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

{
  "version": "v1",
  "authorizedOrganization": "12345678-ABCD-DCBA-ABCD-123456789ABC",
  "createPermission": true,
  "readPermission": true,
  "updatePermission": true,
  "deletePermission": false
}

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.