feat: rewrite Zeebe API auth guide

docs/apis-tools/zeebe-api-rest/zeebe-api-rest-authentication.md

@@ -4,59 +4,136 @@ title: "Authentication"
 description: "Describes authentication options that can be used to access Zeebe REST API."
 ---
 
-## Authentication in the cloud
-
-To access the API endpoint, you need an access token.
-
-Your client must send a header in each request:
-
-`Authorization: Bearer <Token>`
-
-For example, send a request using _curl_:
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+All Zeebe REST API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and include it in each request.
+
+## Generating a token
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+<TabItem value='saas'>
+
+1. [Create client credentials]($docs$/guides/setup-client-connection-credentials/) in the **Clusters > Cluster name > API** tab of [Camunda Console](https://console.camunda.io/).
+2. Add permissions to this client for **Zeebe**.
+3. Upon creating the client, capture the following values required to generate a token:
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   | 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`                           |
+   | Optimize REST Address    | `ZEEBE_REST_ADDRESS`             | -                                            |
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   :::tip
+   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:
+   ```bash
+   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}"
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+1. [Add an M2M application in Identity](/self-managed/identity/user-guide/additional-features/incorporate-applications.md).
+2. [Add permissions to this application](/self-managed/identity/user-guide/additional-features/incorporate-applications.md) for **Zeebe API**.
+3. Capture the `Client ID` and `Client Secret` from the application in Identity.
+4. [Generate a token](/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md) to access the REST API. Provide the `client_id` and `client_secret` from the values you previously captured in Identity.
+   ```shell
+   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'
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+</TabItem>
+
+</Tabs>
+
+## Using 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 Zeebe REST API's `/topology` endpoint:
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+
+<TabItem value='saas'>
+
+:::tip
+The `${ZEEBE_REST_ADDRESS}` variable below represents the URL of the Zeebe REST API. You can capture this URL when creating an API client. You can also construct it as `https://${REGION}.zeebe.camunda.io/${CLUSTER_ID}/`.
+:::
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+:::tip
+The `${ZEEBE_REST_ADDRESS}` variable below represents the URL of the Zeebe REST API. You can configure this value in your Self-Managed installation. The default value is `http://localhost:8080/`.
+:::
+
+</TabItem>
+
+</Tabs>
 
 ```shell
-curl -XGET -H'Accept: application/json' -H'Authorization: Bearer <TOKEN>' http://localhost:8080/v1/topology
+curl --header "Authorization: Bearer ${TOKEN}" \
+     ${ZEEBE_REST_ADDRESS}/v1/topology
 ```
 
-### How to obtain the access token
-
-You must obtain a token to use the Zeebe REST API. When you create a Zeebe [client](/guides/setup-client-connection-credentials.md), you get all the information needed to connect to Zeebe.
-
-Refer to our guide on [building your own client](../build-your-own-client.md).
-
-The following settings are needed:
-
-| Name                     | Description                                     | Default value      |
-| ------------------------ | ----------------------------------------------- | ------------------ |
-| client id                | Name of your registered client                  | -                  |
-| client secret            | Password for your registered client             | -                  |
-| audience                 | Permission name; if not given use default value | `zeebe.camunda.io` |
-| authorization server url | Token issuer server                             | -                  |
-
-Send a token issue _POST_ request to the authorization server with the following content:
+A successful response includes [information about the cluster](/apis-tools/zeebe-api-rest/specifications/get-cluster-topology.api.mdx). For example:
 
 ```json
 {
-  "client_id": "<client-id>",
-  "client_secret": "<client-secret>",
-  "audience": "<audience>",
-  "grant_type": "client_credentials"
+  "brokers": [
+    ...
+  ],
+  "clusterSize": 3,
+  "partitionsCount": 3,
+  "replicationFactor": 3,
+  "gatewayVersion": "8.6.0"
 }
 ```
 
-Refer to the following example with _curl_:
+## Token expiration
 
-```shell
-curl -X POST --header 'content-type: application/json' --data '{"client_id": "<client-id>", "client_secret":"<client-secret>","audience":"<audience>","grant_type":"client_credentials"}' https://<authorization server url>
-```
-
-If the authentication is successful, the authorization server sends back the access token, when it expires, scope, and type:
-
-```json
-{
-  "access_token": "ey...",
-  "scope": "...",
-  "expires_in": 86400,
-  "token_type": "Bearer"
-}
-```
+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.

versioned_docs/version-8.5/apis-tools/zeebe-api-rest/zeebe-api-rest-authentication.md

@@ -4,59 +4,136 @@ title: "Authentication"
 description: "Describes authentication options that can be used to access Zeebe REST API."
 ---
 
-## Authentication in the cloud
-
-To access the API endpoint, you need an access token.
-
-Your client must send a header in each request:
-
-`Authorization: Bearer <Token>`
-
-For example, send a request using _curl_:
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+All Zeebe REST API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and include it in each request.
+
+## Generating a token
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+<TabItem value='saas'>
+
+1. [Create client credentials]($docs$/guides/setup-client-connection-credentials/) in the **Clusters > Cluster name > API** tab of [Camunda Console](https://console.camunda.io/).
+2. Add permissions to this client for **Zeebe**.
+3. Upon creating the client, capture the following values required to generate a token:
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   | 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`                           |
+   | Optimize REST Address    | `ZEEBE_REST_ADDRESS`             | -                                            |
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   :::tip
+   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:
+   ```bash
+   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}"
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+1. [Add an M2M application in Identity](/self-managed/identity/user-guide/additional-features/incorporate-applications.md).
+2. [Add permissions to this application](/self-managed/identity/user-guide/additional-features/incorporate-applications.md) for **Zeebe API**.
+3. Capture the `Client ID` and `Client Secret` from the application in Identity.
+4. [Generate a token](/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md) to access the REST API. Provide the `client_id` and `client_secret` from the values you previously captured in Identity.
+   ```shell
+   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'
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+</TabItem>
+
+</Tabs>
+
+## Using 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 Zeebe REST API's `/topology` endpoint:
+
+<Tabs groupId="environment" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+
+<TabItem value='saas'>
+
+:::tip
+The `${ZEEBE_REST_ADDRESS}` variable below represents the URL of the Zeebe REST API. You can capture this URL when creating an API client. You can also construct it as `https://${REGION}.zeebe.camunda.io/${CLUSTER_ID}/`.
+:::
+
+</TabItem>
+
+<TabItem value='self-managed'>
+
+:::tip
+The `${ZEEBE_REST_ADDRESS}` variable below represents the URL of the Zeebe REST API. You can configure this value in your Self-Managed installation. The default value is `http://localhost:8080/`.
+:::
+
+</TabItem>
+
+</Tabs>
 
 ```shell
-curl -XGET -H'Accept: application/json' -H'Authorization: Bearer <TOKEN>' http://localhost:8080/v1/topology
+curl --header "Authorization: Bearer ${TOKEN}" \
+     ${ZEEBE_REST_ADDRESS}/v1/topology
 ```
 
-### How to obtain the access token
-
-You must obtain a token to use the Zeebe REST API. When you create a Zeebe [client](/guides/setup-client-connection-credentials.md), you get all the information needed to connect to Zeebe.
-
-Refer to our guide on [building your own client](../build-your-own-client.md).
-
-The following settings are needed:
-
-| Name                     | Description                                     | Default value      |
-| ------------------------ | ----------------------------------------------- | ------------------ |
-| client id                | Name of your registered client                  | -                  |
-| client secret            | Password for your registered client             | -                  |
-| audience                 | Permission name; if not given use default value | `zeebe.camunda.io` |
-| authorization server url | Token issuer server                             | -                  |
-
-Send a token issue _POST_ request to the authorization server with the following content:
+A successful response includes [information about the cluster](/apis-tools/zeebe-api-rest/specifications/get-cluster-topology.api.mdx). For example:
 
 ```json
 {
-  "client_id": "<client-id>",
-  "client_secret": "<client-secret>",
-  "audience": "<audience>",
-  "grant_type": "client_credentials"
+  "brokers": [
+    ...
+  ],
+  "clusterSize": 3,
+  "partitionsCount": 3,
+  "replicationFactor": 3,
+  "gatewayVersion": "8.5.7"
 }
 ```
 
-Refer to the following example with _curl_:
+## Token expiration
 
-```shell
-curl -X POST --header 'content-type: application/json' --data '{"client_id": "<client-id>", "client_secret":"<client-secret>","audience":"<audience>","grant_type":"client_credentials"}' https://<authorization server url>
-```
-
-If the authentication is successful, the authorization server sends back the access token, when it expires, scope, and type:
-
-```json
-{
-  "access_token": "ey...",
-  "scope": "...",
-  "expires_in": 86400,
-  "token_type": "Bearer"
-}
-```
+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.