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 Management 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 Management Identity.
4. Generate a token to access the Web Modeler REST API. Provide the client_id and client_secret from the values you previously captured in Management 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
}

Organization-level access

API tokens are granted to organization-level applications (Self-Managed) or clients (SaaS) rather than individual users. With an API token, you can read, edit, and delete all workspaces (called "projects" before Camunda 8.10) and workspace resources in the organization, as long as the application or client has the required Web Modeler API permissions. This is true even if you aren't a member of the workspace and you can't see it in the Camunda Hub user interface.

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.