clean up authorization references

docs/apis-tools/console-api-reference.md

@@ -4,8 +4,6 @@ title: Console API clients (REST)
 description: "Create and manage clusters, and interact with Camunda 8 management API programmatically without using the Camunda 8 Console."
 ---
 
-## Overview
-
 The Camunda 8 management API provides a programmatic interface for managing Camunda clusters and API clients. It offers endpoints for various operations, including cluster backup, creation, and deletion, as well as client and member management. The API also allows for IP whitelisting and secret management.
 
 A detailed API description can be found [here](https://console.cloud.camunda.io/customer-api/openapi/docs/#/) via Swagger. With a valid access token, this offers an interactive API experience against your Camunda 8 cluster.
@@ -22,7 +20,7 @@ For example, send a request using _curl_:
 curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer <TOKEN>" -d '' http://api.cloud.camunda.io/clusters
 ```
 
-For all requests, include the access token in the Authorization header: `authorization:Bearer ${TOKEN}`.
+For all requests, include the access token in the authorization header: `authorization:Bearer ${TOKEN}`.
 
 ### Client credentials and scopes
 

docs/apis-tools/operate-api/authentication.md

@@ -1,6 +1,8 @@
 ---
 id: operate-api-authentication
 title: Authentication
+slug: /apis-tools/operate-api/authentication
+sidebar_position: 2
 description: "Learn about authentication options to access the Operate REST API."
 ---
 

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

@@ -51,7 +51,7 @@ Refer to the following example with _curl_:
 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 authorization is successful, the authorization server sends back the access token, when it expires, scope, and type:
+If the authentication is successful, the authorization server sends back the access token, when it expires, scope, and type:
 
 ```json
 {

docs/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md

@@ -10,6 +10,10 @@ description: "Tasklist API is a REST API and provides searching, getting, and ch
 Tasklist API is a REST API and provides searching, getting, and changing Tasklist data.
 Requests and responses are in JSON notation. Some objects have additional endpoints.
 
+:::note
+Ensure you [authenticate](./tasklist-api-rest-authentication.md) before accessing the Tasklist API.
+:::
+
 ## API documentation as Swagger
 
 A detailed API description is also available as Swagger UI at `https://${base-url}/swagger-ui/index.html`.

docs/apis-tools/tasklist-api/tasklist-api-authentication.md

@@ -0,0 +1,70 @@
+---
+id: tasklist-api-authentication
+title: Authentication
+slug: /apis-tools/tasklist-api/tasklist-api-authentication
+sidebar_position: 2
+description: "Build apps powered by BPMN that require human interaction, and make requests."
+---
+
+Authenticate to access the Tasklist 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_:
+
+```shell
+curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>" -d '{"query": "{tasks(query:{}){name}}"}' http://localhost:8080/graphql
+```
+
+### How to obtain the access token
+
+You must obtain a token to use the Tasklist API. When you create a Tasklist [client](/guides/setup-client-connection-credentials.md), you get all the information needed to connect to Tasklist.
+
+Refer to our guide on [building your own client](/apis-tools/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 | `tasklist.camunda.io` |
+| authorization server url | Token issuer server                             | -                     |
+
+Send a token issue _POST_ request to the authorization server with the following content:
+
+```json
+{
+  "client_id": "<client-id>",
+  "client_secret": "<client-secret>",
+  "audience": "<audience>",
+  "grant_type": "client_credentials"
+}
+```
+
+Refer to the following example with _curl_:
+
+```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"
+}
+```
+
+## Authentication for Self-Managed cluster
+
+The authentication is described in [Tasklist Configuration - Authentication](/self-managed/tasklist-deployment/tasklist-authentication.md#identity).

docs/apis-tools/tasklist-api/tasklist-api-overview.md

@@ -6,7 +6,7 @@ sidebar_position: 1
 description: "Build apps powered by BPMN that require human interaction, and make requests."
 ---
 
-In this document, we'll go over the basics on how to consume the Tasklist GraphQL API. Read more about how to build a real world application [here](../tasklist-api-tutorial).
+In this document, we'll go over the basics on how to consume the Tasklist GraphQL API. Read more about how to build a real world application [here](../tasklist-api-tutorial). Be sure to [authenticate to use the Tasklist API](./tasklist-api-authentication.md).
 
 :::note
 Review the new [Tasklist REST API](../tasklist-api-rest/tasklist-api-rest-overview.md). This API offers the same functionality as the current GraphQL API, but with a more streamlined and efficient way of interacting with our service.
@@ -22,67 +22,6 @@ From Camunda 8 the endpoint is `${base-url}/graphql`.
 
 For SaaS: `https://${REGION}.tasklist.camunda.io:443/${CLUSTER_ID}/graphql`, and for Self-Managed installations: `http://localhost:8080/graphql`.
 
-## 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_:
-
-```shell
-curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>" -d '{"query": "{tasks(query:{}){name}}"}' http://localhost:8080/graphql
-```
-
-### How to obtain the access token
-
-You must obtain a token to use the Tasklist API. When you create a Tasklist [client](/guides/setup-client-connection-credentials.md), you get all the information needed to connect to Tasklist.
-
-Refer to our guide on [building your own client](/apis-tools/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 | `tasklist.camunda.io` |
-| authorization server url | Token issuer server                             | -                     |
-
-Send a token issue _POST_ request to the authorization server with the following content:
-
-```json
-{
-  "client_id": "<client-id>",
-  "client_secret": "<client-secret>",
-  "audience": "<audience>",
-  "grant_type": "client_credentials"
-}
-```
-
-Refer to the following example with _curl_:
-
-```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 authorization 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"
-}
-```
-
-## Authentication for Self-Managed cluster
-
-The authentication is described in [Tasklist Configuration - Authentication](/docs/self-managed/tasklist-deployment/tasklist-authentication/#identity).
-
 ## Obtaining the Tasklist schema
 
 To obtain the Tasklist GraphQL schema, send a request to the endpoint with a GraphQL introspection query as described [here](https://graphql.org/learn/introspection/), or use the [generated API documentation](/docs/apis-tools/tasklist-api/generated.md).

docs/apis-tools/web-modeler-api/authentication.md

@@ -0,0 +1,93 @@
+---
+id: index
+title: Authentication
+sidebar_position: 2
+description: "Web Modeler API is a REST API and provides access to Web Modeler data. Requests and responses are in JSON notation."
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+## Authentication
+
+To authenticate for the API, generate a JWT token depending on your environment and pass it in each request:
+
+<Tabs groupId="authentication" defaultValue="saas" queryString values={
+[
+{label: 'SaaS', value: 'saas' },
+{label: 'Self-Managed', value: 'self-managed' },
+]}>
+
+<TabItem value='saas'>
+
+1. Create client credentials by clicking **Console > Manage (Organization) > Console API > Create New Credentials**.
+2. Add permissions to this client for **Web Modeler API**.
+3. After creating the client, you can download a shell script to obtain a token.
+4. When you run it, you will get something like the following:
+   ```json
+   {
+     "access_token": "eyJhbG...",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+
+</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 **Web Modeler API**.
+3. [Generate a token](/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md) to access the REST API. You will need the `client_id` and `client_secret` from the Identity application you created.
+   ```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'
+   ```
+4. You will get something like the following:
+   ```json
+   {
+     "access_token": "eyJhbG...",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+
+</TabItem>
+
+</Tabs>
+
+## Example usage
+
+1. Take the **access_token** value from the response object and store it as your token.
+2. Send the token as an authorization header in each request. In this case, call the Web Modeler endpoint to validate the token.
+
+   To use the JWT token in the cloud, use the following command:
+
+   ```shell
+   curl -o - 'https://modeler.cloud.camunda.io/api/v1/info' -H 'Authorization: Bearer eyJhb...'
+   ```
+
+   When using a Self-Managed installation, you can use the following command instead:
+
+   ```shell
+   curl -o - 'http://localhost:8070/api/v1/info' -H 'Authorization: Bearer eyJhb...'
+   ```
+
+3. You will get something like the following:
+   ```json
+   {
+     "version": "v1",
+     "authorizedOrganization": "12345678-ABCD-DCBA-ABCD-123456789ABC",
+     "createPermission": true,
+     "readPermission": true,
+     "updatePermission": true,
+     "deletePermission": false
+   }
+   ```

docs/apis-tools/web-modeler-api/index.md

@@ -1,104 +1,22 @@
 ---
 id: index
 title: Web Modeler API (REST)
+sidebar_position: 1
 description: "Web Modeler API is a REST API and provides access to Web Modeler data. Requests and responses are in JSON notation."
 ---
 
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
 Web Modeler provides a REST API at `/api/*`. Clients can access this API by passing a JWT access token in an authorization header `Authorization: Bearer <JWT>`.
 
+:::note
+Ensure you [authenticate](./authentication.md) before accessing the Web Modeler API.
+:::
+
 ## OpenAPI documentation
 
 A detailed API description is available as [OpenAPI](https://www.openapis.org/) specification at [https://modeler.cloud.camunda.io/swagger-ui/index.html](https://modeler.cloud.camunda.io/swagger-ui/index.html)
 for SaaS and at [http://localhost:8070/swagger-ui.html](http://localhost:8070/swagger-ui.html) for Self-Managed
 installations.
 
-## Authentication
-
-To authenticate for the API, generate a JWT token depending on your environment and pass it in each request:
-
-<Tabs groupId="authentication" defaultValue="saas" queryString values={
-[
-{label: 'SaaS', value: 'saas' },
-{label: 'Self-Managed', value: 'self-managed' },
-]}>
-
-<TabItem value='saas'>
-
-1. Create client credentials by clicking **Console > Manage (Organization) > Console API > Create New Credentials**.
-2. Add permissions to this client for **Web Modeler API**.
-3. After creating the client, you can download a shell script to obtain a token.
-4. When you run it, you will get something like the following:
-   ```json
-   {
-     "access_token": "eyJhbG...",
-     "expires_in": 300,
-     "refresh_expires_in": 0,
-     "token_type": "Bearer",
-     "not-before-policy": 0
-   }
-   ```
-
-</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 **Web Modeler API**.
-3. [Generate a token](/self-managed/identity/user-guide/authorizations/generating-m2m-tokens.md) to access the REST API. You will need the `client_id` and `client_secret` from the Identity application you created.
-   ```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'
-   ```
-4. You will get something like the following:
-   ```json
-   {
-     "access_token": "eyJhbG...",
-     "expires_in": 300,
-     "refresh_expires_in": 0,
-     "token_type": "Bearer",
-     "not-before-policy": 0
-   }
-   ```
-
-</TabItem>
-
-</Tabs>
-
-## Example usage
-
-1. Take the **access_token** value from the response object and store it as your token.
-2. Send the token as an authorization header in each request. In this case, call the Web Modeler endpoint to validate the token.
-
-   To use the JWT token in the cloud, use the following command:
-
-   ```shell
-   curl -o - 'https://modeler.cloud.camunda.io/api/v1/info' -H 'Authorization: Bearer eyJhb...'
-   ```
-
-   When using a Self-Managed installation, you can use the following command instead:
-
-   ```shell
-   curl -o - 'http://localhost:8070/api/v1/info' -H 'Authorization: Bearer eyJhb...'
-   ```
-
-3. You will get something like the following:
-   ```json
-   {
-     "version": "v1",
-     "authorizedOrganization": "12345678-ABCD-DCBA-ABCD-123456789ABC",
-     "createPermission": true,
-     "readPermission": true,
-     "updatePermission": true,
-     "deletePermission": false
-   }
-   ```
-
 ## Limitations
 
 When using Web Modeler API: