camunda · alexronquillo · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/docs/apis-tools/migration-manuals/saas-orchestration-architecture.md b/docs/apis-tools/migration-manuals/saas-orchestration-architecture.md
@@ -0,0 +1,87 @@
+---
+id: saas-orchestration-architecture
+title: "SaaS orchestration architecture"
+description: "Learn about the new streamlined SaaS orchestration architecture in Camunda 8.9."
+---
+
+import PageDescription from '@site/src/components/PageDescription';
+
+<PageDescription />
+
+## About
+
+Camunda 8.9 introduces a streamlined SaaS orchestration architecture. The runtime for Operate, Tasklist, Identity (Admin), and the Zeebe REST API is unified into a single orchestration service. Zeebe brokers continue to run separately and execute workflows as before.
+
+This is a topology change in SaaS only and does not affect Self-Managed deployments.
+
+What's new:
+
+- [Unified API domain for Orchestration Clusters](#unified-api-domain-for-orchestration-clusters). Legacy hostnames are deprecated and will remain accessible until 8.10.
+- [New client credentials use new API URLs.](#client-credentials-and-legacy-hostnames)
+- [Cluster Metrics endpoint: `service` labels have changed on Orchestration Cluster metrics.](#service-label-changes)
+
+What didn't change:
+
+- The same UIs for Operate, Tasklist, and Admin/Identity and the REST API remain available as before.
+- The Zeebe gRPC endpoint is unchanged.
+
+## Unified API domain for Orchestration Clusters
+
+Camunda 8.9 introduces a unified API domain for Orchestration Clusters. All services are now accessible under a single base URL:
+
+| Service             | Unified URL (8.9)                                            |
+| :------------------ | :----------------------------------------------------------- |
+| Base / REST API     | `https://<region>.api.<camunda-domain>/<clusterId>`          |
+| Operate UI          | `https://<region>.api.<camunda-domain>/<clusterId>/operate`  |
+| Tasklist UI         | `https://<region>.api.<camunda-domain>/<clusterId>/tasklist` |
+| Admin (Identity) UI | `https://<region>.api.<camunda-domain>/<clusterId>/admin`    |
+
+Legacy hostnames (`*.zeebe.<camunda-domain>`, `*.operate.<camunda-domain>`, `*.tasklist.<camunda-domain>`, and `*.identity.<camunda-domain>`) continue to work in 8.9 and are internally routed to the unified service, but are deprecated and scheduled for removal in 8.10.
+
+After the 8.10 release, only the Zeebe gRPC endpoint and the unified `*.api.*` Ingress will remain.
+
+### Deprecation
+
+Legacy hostnames are deprecated as of 8.9 and will be removed in 8.10. Migrate any hard-coded URLs for Operate, Tasklist, or Identity to the new unified `*.api.*` URLs during the 8.9 lifecycle to ensure readiness before the 8.10 release.
+
+## Client credentials and legacy hostnames
+
+Existing client credentials downloaded from Console for pre-8.9 clusters may reference legacy hostnames. Because those hostnames remain available in 8.9, existing credentials continue to work after a cluster is upgraded to 8.9. No immediate action is required.
+
+### Recommended action
+
+For long-lived automation and CI/CD systems, Camunda recommends updating credentials to use the new unified `*.api.*` URLs and corresponding token audience values before 8.10. You have two options:
+
+- **Update existing credentials manually:** Edit the hostnames and token audience values in your existing credential configuration to reference the new unified URLs.
+- **Create new credentials:** Create a fresh set of client credentials in Camunda Console, which will be generated with the unified API URLs and correct audience values by default.
+
+## Service label changes
+
+<span className="badge badge--breaking-change">Breaking change</span>
+
+Due to the streamlined orchestration architecture introduced in 8.9, metrics previously emitted by the individual Operate, Tasklist, and Identity services are now emitted by the unified orchestration service. As a result, the `service` label on affected metrics will change to reflect the new source service.
+
+This applies to Camunda 8 SaaS clusters using the [Cluster Metrics endpoint](/components/saas/monitoring/cluster-metrics-endpoint/set-up-cluster-metrics-endpoint.md).
+
+### Impact
+
+Monitoring dashboards, alerting rules, or queries that filter or group by the `service` label on Orchestration Cluster metrics may stop matching expected values after upgrading to 8.9, as some metrics will now be emitted by a different source service.
+
+### Action required
+
+After your cluster is upgraded to 8.9, review your dashboards and alerting rules and verify the `service` label values metrics are returning. Update any Prometheus queries or alert definitions that no longer match.
+
+## Upgrade behavior and expected downtime
+
+When a Camunda 8 SaaS Orchestration Cluster is upgraded from 8.8 to 8.9:
+
+1. The existing Operate and Tasklist components are shut down.
+2. The unified orchestration service starts in their place.
+3. Ingress routes are updated so legacy hostnames continue to resolve while the new `*.api.*` endpoints become active.
+
+### Impact during upgrade
+
+- **Web UIs and REST API:** You should expect a short interruption while the old services are removed and the unified service becomes ready.
+- **Workflow execution (Zeebe brokers):** Designed to remain running throughout the upgrade. The primary impact is limited to UI and API availability, not to engine execution state.
+
+To upgrade, initiate the cluster upgrade to 8.9 from Camunda Console. No additional steps are required beyond the URL and credential recommendations above.
diff --git a/docs/apis-tools/operate-api/overview.md b/docs/apis-tools/operate-api/overview.md
@@ -20,7 +20,7 @@ Work with this API in our [Postman collection](https://www.postman.com/camundate
 
 ## Context paths
 
-For SaaS: `https://${REGION}.operate.camunda.io:443/${CLUSTER_ID}/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
+For SaaS: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/operate/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
@@ -36,7 +36,7 @@ See [the interactive Operate API Explorer][operate-api-explorer] for specificati
 
 A Swagger UI is also available within a running instance of Operate, at `https://${base-url}/swagger-ui/index.html`.
 
-For SaaS: `https://${REGION}.operate.camunda.io/${CLUSTER_ID}/swagger-ui.html`, and for Self-Managed installations: `http://localhost:8080/swagger-ui.html`.
+For SaaS: `https://${REGION}.api.camunda.io/${CLUSTER_ID}/operate/swagger-ui.html`, and for Self-Managed installations: `http://localhost:8080/swagger-ui.html`.
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).

diff --git a/...apis-tools/orchestration-cluster-api-mcp/orchestration-cluster-api-mcp-setup.md b/...apis-tools/orchestration-cluster-api-mcp/orchestration-cluster-api-mcp-setup.md
@@ -83,7 +83,7 @@ The MCP server is served at `/mcp/cluster` on the Orchestration Cluster. The ful
 | :------------------------- | :------------------------------------------------------------------------------ |
 | Camunda 8 Run              | `http://localhost:8080/mcp/cluster`                                             |
 | Docker Compose             | `http://localhost:8080/mcp/cluster`                                             |
-| SaaS – public connectivity | `https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/mcp/cluster`               |
+| SaaS – public connectivity | `https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/mcp/cluster`                 |
 | SaaS – secure connectivity | `https://${CLUSTER_ID}.${REGION_ID}.privateconnectivity.camunda.io/mcp/cluster` |
 | Self-Managed (custom)      | `https://<your-host>/mcp/cluster`                                               |
 
@@ -140,13 +140,13 @@ Add the following to your MCP client configuration (for example, `.vscode/mcp.js
 }
 ```
 
-| Variable                 | Description                                                                                                                                                                                                      |
-| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `CAMUNDA_BASE_URL`       | Base URL of your Orchestration Cluster, **without** the `/mcp/cluster` path (for example, the public `zeebe.camunda.io` URL or the private `privateconnectivity.camunda.io` URL when using Secure connectivity). |
-| `CAMUNDA_CLIENT_ID`      | OAuth client ID from your API client credentials.                                                                                                                                                                |
-| `CAMUNDA_CLIENT_SECRET`  | OAuth client secret from your API client credentials.                                                                                                                                                            |
-| `CAMUNDA_OAUTH_URL`      | OAuth token endpoint URL.                                                                                                                                                                                        |
-| `CAMUNDA_TOKEN_AUDIENCE` | Token audience for the Orchestration Cluster API.                                                                                                                                                                |
+| Variable                 | Description                                                                                                                                                                                                    |
+| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CAMUNDA_BASE_URL`       | Base URL of your Orchestration Cluster, **without** the `/mcp/cluster` path (for example, the public `api.camunda.io` URL or the private `privateconnectivity.camunda.io` URL when using Secure connectivity). |
+| `CAMUNDA_CLIENT_ID`      | OAuth client ID from your API client credentials.                                                                                                                                                              |
+| `CAMUNDA_CLIENT_SECRET`  | OAuth client secret from your API client credentials.                                                                                                                                                          |
+| `CAMUNDA_OAUTH_URL`      | OAuth token endpoint URL.                                                                                                                                                                                      |
+| `CAMUNDA_TOKEN_AUDIENCE` | Token audience for the Orchestration Cluster API.                                                                                                                                                              |
 
 :::tip Where to find these values
 When you [create API client credentials](/components/console/manage-clusters/manage-api-clients.md#create-a-client) in the Camunda Console, all required connection details — including the base URL, OAuth endpoint, client ID, and audience — are displayed on the credentials page. You can also copy a ready-to-use `c8ctl` configuration snippet directly from the **MCP** tab on the credentials screen.
@@ -198,7 +198,7 @@ camunda:
             camunda-mcp:
               type: http
               http:
-                url: https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/mcp/cluster
+                url: https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/mcp/cluster
                 authentication:
                   type: oauth
                   oauth:

diff --git a/...tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md b/...tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-overview.md
@@ -80,7 +80,7 @@ curl http://localhost:8080/v2/topology
 SaaS, public connectivity:
 
 ```bash
-curl https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/v2/topology
+curl https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/v2/topology
 ```
 
 SaaS, secure connectivity (AWS PrivateLink):
@@ -123,7 +123,7 @@ This section covers the technical details and conventions you need to understand
 
 In the Camunda Console, go to your cluster, and in the Cluster Details, find your **Region Id** and **Cluster Id**.
 
-- For public connectivity (default), use this pattern as your `${BASE_URL}`: `https://${REGION_ID}.zeebe.camunda.io/${CLUSTER_ID}/v2/`
+- For public connectivity (default), use this pattern as your `${BASE_URL}`: `https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/v2/`
 
 - For secure connectivity (AWS PrivateLink), use the private base URL shown in Console. For the Orchestration Cluster REST API, the pattern is:
 

diff --git a/...-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger.md b/...-tools/orchestration-cluster-api-rest/orchestration-cluster-api-rest-swagger.md
@@ -30,15 +30,15 @@ For SaaS clusters, Swagger UI is accessible through your cluster's dedicated end
 
 1. In the Camunda Console, go to your cluster
 2. In **Cluster Details**, find your **Region ID** and **Cluster ID**
-3. Use this URL format: `https://${REGION_ID}.operate.camunda.io/${CLUSTER_ID}/swagger`
+3. Use this URL format: `https://${REGION_ID}.api.camunda.io/${CLUSTER_ID}/swagger`
 
 :::note
 Swagger UI is protected with CSRF. If you are logged into the Camunda Console, you can access Swagger UI directly. If not, you may need to log in first.
 :::
 
-**Example:**  
+**Example:**
 If your Region ID is `bru-2` and Cluster ID is `abc123-def456-ghi789`, your Swagger UI URL would be:
-`https://bru-2.operate.camunda.io/abc123-def456-ghi789/swagger`
+`https://bru-2.api.camunda.io/abc123-def456-ghi789/swagger`
 
 ### Self-Managed
 

diff --git a/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md b/docs/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md
@@ -17,7 +17,7 @@ Ensure you [authenticate](./tasklist-api-rest-authentication.md) before accessin
 
 ## Context paths
 
-For SaaS: `https://${REGION}.tasklist.camunda.io:443/${CLUSTER_ID}/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
+For SaaS: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/v1/`, and for Self-Managed installations: `http://localhost:8080/v1/`.
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
@@ -33,7 +33,7 @@ See [the interactive Tasklist REST API Explorer][tasklist-api-explorer] for spec
 
 A detailed API description is also available as a Swagger UI at `https://${base-url}/swagger-ui/index.html`.
 
-For SaaS: `https://${REGION}.tasklist.camunda.io:443/${CLUSTER_ID}/swagger-ui/index.html`, and for Self-Managed installations: [`http://localhost:8080/swagger-ui/index.html`](http://localhost:8080/swagger-ui/index.html).
+For SaaS: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/swagger-ui/index.html`, and for Self-Managed installations: [`http://localhost:8080/swagger-ui/index.html`](http://localhost:8080/swagger-ui/index.html).
 
 :::note
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).

diff --git a/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md b/docs/apis-tools/zeebe-api-rest/zeebe-api-rest-overview.md
@@ -18,7 +18,7 @@ Ensure you [authenticate](./zeebe-api-rest-authentication.md) before accessing t
 
 Find your **region Id** and **cluster Id** under **Connection information** in your client credentials (revealed when you click on your client under the **API** tab within your cluster).
 
-Example path: `https://${REGION}.zeebe.camunda.io:443/${CLUSTER_ID}/v1/`
+Example path: `https://${REGION}.api.camunda.io:443/${CLUSTER_ID}/v1/`
 
 ### Self-Managed
 

diff --git a/docs/components/camunda-integrations/servicenow/setup-and-configuration.md b/docs/components/camunda-integrations/servicenow/setup-and-configuration.md
@@ -79,7 +79,7 @@ Ensure the following prerequisites are in place:
 | Domain              | `Global`                                                           |
 | Connection alias ID | `x_camun_camunda.Camunda`                                          |
 | URL Builder         | Enabled                                                            |
-| Host                | Camunda cluster Region ID (e.g., `lhr-1.zeebe.camunda.io`)         |
+| Host                | Camunda cluster Region ID (e.g., `lhr-1.api.camunda.io`)           |
 | Protocol            | `https`                                                            |
 | Base path           | Camunda Cluster ID (e.g., `/6b6b3969-a65c-4bdd-905e-c29102eebded`) |
 

diff --git a/docs/components/connectors/custom-built-connectors/host-custom-connector.md b/docs/components/connectors/custom-built-connectors/host-custom-connector.md
@@ -33,7 +33,7 @@ docker run --rm --name=CustomConnectorInSaaS \
     -e CAMUNDA_CLIENT_CLOUD_CLIENT-ID='<YOUR_CLIENT_ID>' \
     -e CAMUNDA_CLIENT_CLOUD_CLIENT-SECRET='<YOUR_CLIENT_SECRET>' \
     -e CAMUNDA_CLIENT_CLOUD_REGION='<YOUR_CLUSTER_REGION>' \
-    -e CAMUNDA_OPERATE_CLIENT_URL='https://<region>.operate.camunda.io/<cluster-id>' \
+    -e CAMUNDA_OPERATE_CLIENT_URL='https://<region>.api.camunda.io/<cluster-id>' \
         camunda/connectors-bundle:<desired-version>
 ```
 

diff --git a/...ents/modeler/web-modeler/modeling/advanced-modeling/publish-public-processes.md b/...ents/modeler/web-modeler/modeling/advanced-modeling/publish-public-processes.md
@@ -102,7 +102,7 @@ Unfortunately, currently you can not define granular permissions for shared proc
 
 Check the link URL. It should follow this pattern:
 
-`https://<region-identifier>.tasklist.camunda.io/<cluster-uuid>/new/<process-ID>`
+`https://<region-identifier>.api.camunda.io/<cluster-uuid>/new/<process-ID>`
 
 ### Are public links indexed by search engines?
 

diff --git a/sidebars.js b/sidebars.js
@@ -1406,6 +1406,7 @@ module.exports = {
         "apis-tools/migration-manuals/migrate-to-camunda-spring-boot-starter",
         "apis-tools/migration-manuals/migrate-to-camunda-process-test",
         "apis-tools/migration-manuals/migrate-from-grpc-to-orchestration-cluster-api",
+        "apis-tools/migration-manuals/saas-orchestration-architecture",
       ],
     },
   ],