Authentication

Authenticate your requests to the Camunda Hub REST API.

The process

Generate a JSON Web Token (JWT), and include it in every request. If you already have a client or token for Web Modeler API v1, you can reuse it for this API.

Prerequisites

Before you begin, make sure you have the Admin user role.

Generate a token

1. In Camunda Hub, under Organization overview, click Admin APIs.
2. From the Administration API management page, click Create new credentials.
3. Name the client, and grant it access to the Web Modeler API with the necessary permissions.
4. Click Create, and 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 you create client credentials, the client secret is only shown once. Save the client secret somewhere safe.

5. 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 response looks like this:

   {
     "access_token": "<TOKEN>",
     "expires_in": 300,
     "refresh_expires_in": 0,
     "token_type": "Bearer",
     "not-before-policy": 0
   }

6. Use the access_token in the next step.

Authenticate with your token

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

For example, send a request to the Camunda Hub API's /files/search endpoint:

curl --header "Authorization: Bearer ${TOKEN}" \
     https://hub.cloud.camunda.io/api/v2/files/search

Token expiration

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