From 4ff00ae2ccce55d6a5d8912343b95bf1802eae3c Mon Sep 17 00:00:00 2001 From: GSmithApps Date: Tue, 2 Dec 2025 11:14:59 -0600 Subject: [PATCH 1/4] added clarifications for API key + high avail --- .../cloud/get-started/api-keys.mdx | 14 +++++------ .../cloud/get-started/namespaces.mdx | 23 +++++++++++++++---- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/production-deployment/cloud/get-started/api-keys.mdx b/docs/production-deployment/cloud/get-started/api-keys.mdx index 35e157084a..9e5cb1f12f 100644 --- a/docs/production-deployment/cloud/get-started/api-keys.mdx +++ b/docs/production-deployment/cloud/get-started/api-keys.mdx @@ -341,17 +341,17 @@ Workflow access secure. ## API keys for Namespace authentication {#namespace-authentication} Create a Namespace with API key authentication as an alternative to mTLS-based authentication by selecting "Allow API -key authentication" during setup. The gRPC endpoint format for the Namespace depends on the authentication method: +key authentication" during setup. The gRPC endpoint format for the Namespace depends on the authentication method and whether or not High Availability features are enabled: -- For API key connections, use the gRPC regional endpoint `..api.temporal.io:7233`. - -Use this gRPC endpoint in the Temporal CLI or SDK to connect to Temporal Cloud with an API key. +- For API key connections on Namespaces without High Availability features, use the gRPC regional endpoint `..api.temporal.io:7233`. +- For API Key connections on [Namespaces with High Availability features](/cloud/high-availability), use the +gRPC Namespace endpoint: `..tmprl.cloud:7233`. This allows automated failover without needing to +switch endpoints. :::info -For [Namespaces with High Availability features](/cloud/high-availability) with API key authentication enabled, use the -gRPC Namespace endpoint: `..tmprl.cloud:7233`. This allows automated failover without needing to -switch endpoints. +The difference between the two endpoints means that when switching on or off High Availability features for a Namespace, you may need to update the gRPC endpoint used by your clients. +See [Disable High Availability](/cloud/high-availability/enable#disable) for more information. ::: diff --git a/docs/production-deployment/cloud/get-started/namespaces.mdx b/docs/production-deployment/cloud/get-started/namespaces.mdx index 61113ccd58..3750b405fc 100644 --- a/docs/production-deployment/cloud/get-started/namespaces.mdx +++ b/docs/production-deployment/cloud/get-started/namespaces.mdx @@ -251,14 +251,29 @@ Sample workflowId convention: Temporal Cloud normally supports authentication to Namespaces using [API keys](/cloud/api-keys) _or_ [mTLS](/cloud/certificates). If you need to migrate from one authentication method to another, or you require both API key and mTLS authentication to be enabled on your Namespace, please contact [Support](https://docs.temporal.io/cloud/support#support-ticket). +:::info + +Requiring both API key and mTLS is in [public preview](/evaluate/development-production-features/release-stages), and doesn't currently support [High Availability features](/cloud/high-availability). + +::: + See the documentation for [API keys](/cloud/api-keys) and [mTLS certificates](/cloud/certificates) for more information on how to create and manage your credentials. Authentication methods require specific endpoints in order to programmatically access your Namespace. +There are two types of gRPC endpoints for accessing a Namespace in Temporal Cloud: a namespace endpoint (`..tmprl.cloud:7233`) and a regional endpoint (`..api.temporal.io:7233`). +Which one to use depends on your authentication method and whether your Namespace has [High Availability features](/cloud/high-availability) enabled, as shown in the table below. -- For the API key authentication method, use the gRPC regional endpoint `..api.temporal.io:7233`. -- For the mTLS authentication method, use the gRPC Namespace endpoint `..tmprl.cloud:7233`. -- For [Namespaces with High Availability features](/cloud/high-availability) use the gRPC Namespace endpoint `..tmprl.cloud:7233`, regardless of your authentication method. - This allows automated failover without needing to switch your endpoint. +| | Not High Availability | High Availability | +|------------------------|-----------------------|----------------------------------------------------------------------------------| +| mTLS Authentication | Namespace | Namespace | +| API Key Authentication | Regional | Both work, but Namespace is recommended because it allows for automated failover | + +:::info + +The difference between the two endpoints for API Key Authentication means that when switching on or off High Availability features for a Namespace, you may need to update the gRPC endpoint used by your clients. +See [Disable High Availability](/cloud/high-availability/enable#disable) for more information. + +::: For information on how to connect to Clients using a specific authentication method see the following documentation. From ad4aec6c6e735d5d10ead6c2eebe47d1ebf531ab Mon Sep 17 00:00:00 2001 From: Grant <14.gsmith.14@gmail.com> Date: Tue, 2 Dec 2025 12:25:44 -0600 Subject: [PATCH 2/4] Update docs/production-deployment/cloud/get-started/namespaces.mdx Co-authored-by: Lanie Hei --- docs/production-deployment/cloud/get-started/namespaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/production-deployment/cloud/get-started/namespaces.mdx b/docs/production-deployment/cloud/get-started/namespaces.mdx index 3750b405fc..b01bf020fe 100644 --- a/docs/production-deployment/cloud/get-started/namespaces.mdx +++ b/docs/production-deployment/cloud/get-started/namespaces.mdx @@ -266,7 +266,7 @@ Which one to use depends on your authentication method and whether your Namespac | | Not High Availability | High Availability | |------------------------|-----------------------|----------------------------------------------------------------------------------| | mTLS Authentication | Namespace | Namespace | -| API Key Authentication | Regional | Both work, but Namespace is recommended because it allows for automated failover | +| API Key Authentication | Regional | Both work, but Namespace is recommended because it reduces the unavailability window during a failover event | :::info From 767e0c6a526388e33ffe5ca01f114ea84479e7de Mon Sep 17 00:00:00 2001 From: Grant <14.gsmith.14@gmail.com> Date: Wed, 3 Dec 2025 11:14:15 -0600 Subject: [PATCH 3/4] Update docs/production-deployment/cloud/get-started/api-keys.mdx Co-authored-by: Lanie Hei --- docs/production-deployment/cloud/get-started/api-keys.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/production-deployment/cloud/get-started/api-keys.mdx b/docs/production-deployment/cloud/get-started/api-keys.mdx index 9e5cb1f12f..91b47ff04b 100644 --- a/docs/production-deployment/cloud/get-started/api-keys.mdx +++ b/docs/production-deployment/cloud/get-started/api-keys.mdx @@ -345,8 +345,7 @@ key authentication" during setup. The gRPC endpoint format for the Namespace dep - For API key connections on Namespaces without High Availability features, use the gRPC regional endpoint `..api.temporal.io:7233`. - For API Key connections on [Namespaces with High Availability features](/cloud/high-availability), use the -gRPC Namespace endpoint: `..tmprl.cloud:7233`. This allows automated failover without needing to -switch endpoints. +gRPC Namespace endpoint: `..tmprl.cloud:7233`. This allows automated failover without needing to configure worker(s) with both endpoints. These endpoints will still work, but in the event of a failover, there is a brief period of unavailability between your workers and Temporal server. :::info From 17484453976d9191f23ea02e97c26c8ec85bea1d Mon Sep 17 00:00:00 2001 From: GSmithApps Date: Wed, 3 Dec 2025 13:52:59 -0600 Subject: [PATCH 4/4] responded to PR comments --- .../cloud/get-started/api-keys.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/production-deployment/cloud/get-started/api-keys.mdx b/docs/production-deployment/cloud/get-started/api-keys.mdx index 91b47ff04b..5bf11b4d7c 100644 --- a/docs/production-deployment/cloud/get-started/api-keys.mdx +++ b/docs/production-deployment/cloud/get-started/api-keys.mdx @@ -341,11 +341,9 @@ Workflow access secure. ## API keys for Namespace authentication {#namespace-authentication} Create a Namespace with API key authentication as an alternative to mTLS-based authentication by selecting "Allow API -key authentication" during setup. The gRPC endpoint format for the Namespace depends on the authentication method and whether or not High Availability features are enabled: +key authentication" during setup. The gRPC endpoint format for the Namespace depends on the authentication method and whether or not High Availability features are enabled. -- For API key connections on Namespaces without High Availability features, use the gRPC regional endpoint `..api.temporal.io:7233`. -- For API Key connections on [Namespaces with High Availability features](/cloud/high-availability), use the -gRPC Namespace endpoint: `..tmprl.cloud:7233`. This allows automated failover without needing to configure worker(s) with both endpoints. These endpoints will still work, but in the event of a failover, there is a brief period of unavailability between your workers and Temporal server. +See the following documentation for [accessing Namespaces](/cloud/namespaces#access-namespaces) for more information. :::info @@ -354,7 +352,13 @@ See [Disable High Availability](/cloud/high-availability/enable#disable) for mor ::: -See the following documentation for [accessing Namespaces](/cloud/namespaces#access-namespaces) for more information. +### Without High Availability features + +Use the gRPC regional endpoint `..api.temporal.io:7233`. + +### With High Availability features + +Use the gRPC Namespace endpoint: `..tmprl.cloud:7233`. This allows automated failover without needing to configure worker(s) with both endpoints. These endpoints will still work, but in the event of a failover, there is a brief period of unavailability between your workers and Temporal server. ## Use API keys to authenticate {#using-apikeys}