Merge branch 'main' into 3162-add-textract-documentation

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

@@ -6,7 +6,7 @@ sidebar_position: 2
 description: "Learn about access tokens and client credentials and scopes to get started with the Administration API."
 ---
 
-All Administration API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and pass it in each request.
+All Administration 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
 
@@ -47,16 +47,16 @@ All Administration API requests require authentication. To authenticate, generat
 
 ## Using a token
 
-Include the captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
+Include the previously captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
 
-For example, to call the Administration API's `/members` endpoint, send the following request:
+For example, to send a request to the Administration API's `/members` endpoint:
 
 ```shell
 curl --header "Authorization: Bearer ${TOKEN}" \
      https://api.cloud.camunda.io/members
 ```
 
-A successful response would include [a list of organization members](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetMembers). For example:
+A successful response includes [a list of organization members](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetMembers). For example:
 
 ```json
 [

docs/apis-tools/administration-sm-api/administration-sm-api-authentication.md

@@ -5,34 +5,61 @@ sidebar_position: 2
 description: "The Administration API for Self-Managed is a REST API and provides access to Console Self-Managed data. Requests and responses are in JSON notation."
 ---
 
-To authenticate for the API, generate a JWT token and pass it in each request:
+All Administration Self-Managed 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
 
 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 **Administration Self-Managed 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.
+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 "client_id=${CLIENT_ID}" \
+   --data-urlencode "client_secret=${CLIENT_SECRET}" \
    --data-urlencode 'grant_type=client_credentials'
    ```
-4. You will get something like the following:
+5. A successful authentication response looks like the following:
    ```json
    {
-     "access_token": "eyJhbG...",
+     "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.
 
-## Example usage
+## Using a token
 
-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.
+Include the previously captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
 
-   ```shell
-   curl -o - 'http://localhost:8080/admin-api/clusters' -H 'Authorization: Bearer eyJhb...'
-   ```
+For example, to send a request to the ["Get current clusters" endpoint](./specifications/get-clusters.api.mdx):
+
+:::tip
+The `${CAMUNDA_BASE_URL}` variable below represents the URL of the Self-Managed environment. You can configure this value in your Self-Managed installation. The default value is `http://localhost:8080`.
+:::
+
+```shell
+curl --request GET ${CAMUNDA_BASE_URL}/admin-api/clusters \
+   --header "Authorization: Bearer ${TOKEN}"
+```
+
+A successful response includes [cluster information](./specifications/get-clusters.api.mdx). For example:
+
+```json
+[
+  {
+    "uuid": "12345",
+    "name": "cluster-1",
+    "status": "healthy",
+    ...
+  }
+]
+```
+
+## 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.

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

@@ -7,7 +7,7 @@ description: "Step through authentication options that can be used to access Cam
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-All Camunda 8 REST API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) depending on your environment and pass it in each request.
+All Camunda 8 REST API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) depending on your environment and include it in each request.
 
 ## Generating a token
 
@@ -88,9 +88,9 @@ All Camunda 8 REST API requests require authentication. To authenticate, generat
 
 ## Using a token
 
-Include the captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
+Include the previously captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
 
-For example, to call the Camunda 8 REST API's `/topology` endpoint, send the following request against the target environment:
+For example, to send a request to the Camunda 8 REST API's `/topology` endpoint:
 
 <Tabs groupId="environment" defaultValue="saas" queryString values={
 [
@@ -121,7 +121,7 @@ curl --header "Authorization: Bearer ${TOKEN}" \
      ${ZEEBE_REST_ADDRESS}/v2/topology
 ```
 
-A successful response would include [information about the cluster](/apis-tools/camunda-api-rest/specifications/get-cluster-topology.api.mdx). For example:
+A successful response includes [information about the cluster](/apis-tools/camunda-api-rest/specifications/get-cluster-topology.api.mdx). For example:
 
 ```json
 {

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

@@ -27,13 +27,14 @@ See [the interactive Camunda 8 REST API Explorer][camunda-api-explorer] for spec
 ### Query API
 
 :::warning
-Query API endpoints do not currently support [resource authorizations][resource authorizations], and can be used to expand user access to restricted resources. If you use resource permissions, allowing public access to those endpoints is not recommended.
+Query API endpoints do not currently support [resource authorizations][], and can be used to expand user access to restricted resources. If you use resource permissions, allowing public access to those endpoints is not recommended.
 :::
 
-All Query API endpoints contain an `(experimental)` declaration. Those endpoints are not accessible by default in Camunda 8 clusters.
+All Query API endpoints contain an `(alpha)` declaration. Those endpoints are not accessible by default in Camunda 8 clusters.
 
-You can enable the experimental search endpoints by setting either the configuration property `camunda.rest.query.enabled` to `true`,
+You can enable the [alpha feature][] search endpoints by setting either the configuration property `camunda.rest.query.enabled` to `true`,
 or the environment variable `CAMUNDA_REST_QUERY_ENABLED` to `true`.
 
 [camunda-api-explorer]: ./specifications/camunda-8-rest-api.info.mdx
 [resource authorizations]: /self-managed/concepts/access-control/resource-authorizations.md
+[alpha feature]: /reference/alpha-features.md