Merge branch 'main' into camper/missing-dependency-cooldown-finding-cooldown-documentation

Author: brianmacdonald-temporal

docs/best-practices/cloud-access-control.mdx

@@ -22,6 +22,13 @@ Temporal Cloud supports two secure authentication methods for Workers:
 
 Both options help secure communication between workers and Temporal Cloud. Choosing the right method and managing it properly is key to maintaining security and minimizing downtime. 
 
+Use this page to define your operating model for machine access to Temporal Cloud. For setup steps and product-specific
+mechanics, see [Manage API keys](/cloud/api-keys) and [Manage service accounts](/cloud/service-accounts).
+
+Related guidance:
+- [Namespace best practices](/best-practices/managing-namespace)
+- [Multi-tenant application patterns](/production-deployment/multi-tenant-patterns)
+
 The high-level end-to-end rotation process is:
 
 1. **Generate new credentials**: Create new certificates or API keys in Temporal Cloud before the current ones expire
@@ -45,17 +52,64 @@ In the case that you are using multiple certificates signed by the same CA, and
 
 One convention is to give certificates a common name that matches the namespace. If you do this when using the same CA for dev and prod, then you can leverage Certificate Filters to prevent access to production environments. This is described in detail under the [authorization section](https://docs.temporal.io/cloud/certificates#control-authorization) of the documentation. 
 
-## Best practices: 
-#### 1. Establish clear guidelines on authentication methods: Teams should standardize on either [mTLS certificates](https://docs.temporal.io/cloud/certificates) or [API keys](https://docs.temporal.io/cloud/api-keys) for the following operations:
+## Best practices
+
+### Establish clear guidelines on authentication methods
+
+Teams should standardize on either [mTLS certificates](https://docs.temporal.io/cloud/certificates) or
+[API keys](https://docs.temporal.io/cloud/api-keys) for the following operations:
 - Connect Temporal clients to Temporal Cloud (e.g. Worker processes)
 - Automation (e.g. Temporal Cloud [Operations API](https://docs.temporal.io/ops), [Terraform provider](https://docs.temporal.io/cloud/terraform-provider), [Temporal CLI](https://docs.temporal.io/cli/setup-cli))
 
-    By default, it is recommended for teams to use API keys and [service accounts](https://docs.temporal.io/cloud/service-accounts) for both operations because API keys are easier to manage and rotate for most teams. In addition, you can control account-level and namespace-level roles for service accounts. 
+By default, teams should use API keys with [service accounts](/cloud/service-accounts) for both operations. API keys
+are generally easier to set up and rotate than mTLS certificates, and service accounts let you assign account-level and
+namespace-level roles.
+
+If your organization requires mutual authentication and stronger cryptographic guarantees, use
+[mTLS certificates](/cloud/certificates) to authenticate Temporal clients to Temporal Cloud and use API keys for
+automation, because the Temporal Cloud [Operations API](/ops) and [Terraform provider](/cloud/terraform-provider) only
+support API key authentication. Unlike API keys tied to users or service accounts, mTLS certificate authentication is
+not tied to Temporal Cloud RBAC identities. Namespace access is based on CA trust, with optional
+[Certificate Filters](/cloud/certificates#manage-certificate-filters) to narrow access by Common Name.
+
+### Default operating model for service accounts and API keys
+
+For most organizations, use the following defaults:
+
+- Create one Service Account per service or worker deployment, not one shared Service Account for an entire team
+- Use account-level Service Accounts only when a service genuinely needs cross-Namespace or account-wide access
+- Prefer Namespace-scoped Service Accounts when a service should only access one Namespace
+- Grant Service Accounts namespace-level access only to the specific Namespaces they need
+
+This approach gives you cleaner ownership, easier rotation, and better auditability than sharing a single machine
+identity across multiple services.
+
+### Use access boundaries that match your Namespace boundaries
+
+The way you partition Namespaces should usually match the way you partition machine identities.
+
+- If multiple services share a Namespace, you may still want one Service Account per service so that each deployment can
+  rotate credentials independently.
+- If you split workloads into separate Namespaces for security, capacity, or team ownership reasons, those Namespaces
+  should usually have separate Service Accounts and API keys as well.
+- If you use Namespace-per-tenant isolation, expect your credential model and RBAC model to become correspondingly more
+  granular.
+
+For more on topology tradeoffs, see [Namespace best practices](/best-practices/managing-namespace) and
+[Multi-tenant application patterns](/production-deployment/multi-tenant-patterns).
+
+### Rotate credentials without downtime
+
+Use the following sequence when rotating credentials:
 
-    If your organization requires mutual authentication and stronger cryptographic guarantees, then it is encouraged for your teams to use mTLS certificates to authenticate Temporal clients to Temporal Cloud and use API keys for automation (because Temporal Cloud [Operations API](https://docs.temporal.io/ops) and [Terraform provider](https://docs.temporal.io/cloud/terraform-provider) only supports API key for authentication)
+1. Create the replacement credential before the existing one expires.
+2. For API keys, create the new valid key while the old key still works, then roll your Workers and clients to use the new key.
+3. For client certificates, stage the new certificate before removing the old one when your deployment process supports that transition.
+4. Validate connectivity and normal Workflow execution using the new credential.
+5. Remove the old credential only after all clients and Workers have switched.
 
-#### 2. Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`):
+### Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`)
 
-  Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.   
+Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement.   
 
-  If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production. 
+If you do this when using the same CA for dev and prod environments, then you can leverage Certificate Filters to prevent access to production. 

docs/best-practices/managing-aps-limits.mdx

@@ -175,7 +175,11 @@ An APS limit is set per Namespace, so multiple use cases with multiple traffic p
 
 #### How to Mitigate
 
-Plan for a set of Namespaces (one per environment) per use case. See [Managing a Namespace](/best-practices/managing-namespace) for more details.
+Plan for a set of Namespaces (one per environment) per use case. This gives each use case its own APS envelope and
+reduces the blast radius when one workload spikes or misbehaves.
+
+If you are deciding whether to split by use case, service, or domain, see
+[Managing a Namespace](/best-practices/managing-namespace) for a topology decision framework.
 
 ## Provisioned Capacity and TRUs
 

docs/best-practices/managing-namespace.mdx

@@ -27,6 +27,15 @@ For reference documentation, see:
 A [Namespace](/namespaces) is a unit of isolation within the Temporal Platform.
 It ensures that Workflow Executions, Task Queues, and resources are logically separated, preventing conflicts and enabling safe multi-tenant usage.
 
+Use this page to decide how many Namespaces you need and where to draw boundaries between environments, services,
+domains, and tenants. For Cloud-specific namespace mechanics such as creation, tagging, and gRPC endpoints, see
+[Namespaces (Temporal Cloud)](/cloud/namespaces).
+
+Related guidance:
+- [Managing Temporal Cloud access control](/best-practices/cloud-access-control)
+- [Multi-tenant application patterns](/production-deployment/multi-tenant-patterns)
+- [Managing Actions per Second (APS) limits in Temporal Cloud](/best-practices/managing-aps-limits)
+
 ## Naming Conventions
 
 ### Use lowercase and hyphens
@@ -66,30 +75,72 @@ If you need to include region, use short codes (e.g., `aps1`, `use1`).
 
 ## Organizational Patterns
 
+### Choose your Namespace boundary intentionally
+
+Start with the smallest number of Namespaces that gives you clear ownership and safe isolation.
+In Temporal Cloud, a Namespace boundary affects:
+
+- [APS limits](/cloud/limits#actions-per-second) and rate limiting
+- access control and credential scope
+- blast radius for misconfigured or overloaded Workers
+- observability boundaries for dashboards and alerts
+- operational overhead for provisioning, tagging, and lifecycle management
+
+Use the following decision table as a starting point:
+
+| If you need... | Prefer... | Why |
+|---|---|---|
+| Basic environment isolation for a single application or use case | Namespace per use case and environment | This is the simplest pattern and works well for most initial deployments |
+| Separate operational ownership for services within the same use case | Namespace per use case, service, and environment | This isolates credentials, limits, and operational changes per service |
+| Stronger boundaries across teams, domains, or business capabilities | Namespace per use case, domain, and environment | This reduces blast radius and lets teams own their own Namespace contracts |
+| Tenant-specific credentials, rate limits, or compliance boundaries | Namespace per tenant | Use this only for a small number of high-value tenants because of the operational overhead |
+
+As a default, start with one Namespace per use case and environment. Split later when APS pressure, security
+requirements, ownership boundaries, or troubleshooting needs justify the extra operational cost.
+
 ### Pattern 1: Namespace per use case and environment
 
 For simple configurations without multiple services or team boundaries.
 
-**Naming convention**: `<use-case>_<environment>`
+**Naming convention**: `<use-case>-<environment>`
+
+**Example**: `payments-prd`, `orders-dev`
 
-**Example**: `payments_prod`, `orders_dev`
+Choose this pattern when:
+
+- one team owns the use case
+- environments need clean separation
+- workload volume and criticality do not yet require further isolation
 
 ### Pattern 2: Namespace per use case, service, and environment
 
 When multiple services that are part of the same use case communicate externally to Temporal via API (HTTP/gRPC).
 
-**Naming convention**: `<use-case>_<service>_<environment>`
+**Naming convention**: `<use-case>-<service>-<environment>`
+
+**Example**: `payments-gateway-prd`, `payments-processor-prd`
+
+Choose this pattern when:
 
-**Example**: `payments_gateway_prod`, `payments_processor_prod`
+- services need separate credentials or access policies
+- one service can exhaust APS or operational limits independently of the others
+- teams want separate ownership of deployment, alerting, or on-call boundaries
 
 ### Pattern 3: Namespace per use case, domain, and environment
 
 When multiple services need to communicate with each other, use [Temporal Nexus](/nexus) to connect Workflows across Namespace boundaries.
 This provides better security, fault isolation, and modularity than sharing a Namespace.
 
-**Naming convention**: `<use-case>_<domain>_<environment>`
+**Naming convention**: `<use-case>-<domain>-<environment>`
 
-**Example**: `payments_checkout_prod`, `payments_refunds_prod`
+**Example**: `payments-checkout-prd`, `payments-refunds-prd`
+
+Choose this pattern when:
+
+- multiple teams or domains need independent release cadence and ownership
+- failures in one domain should not affect the others
+- you want a stronger permission boundary between capabilities
+- you plan to expose cross-Namespace contracts through Nexus
 
 For systems without Nexus, services can communicate via [Signals](/sending-messages#sending-signals) or [Child Workflows](/child-workflows) within the same Namespace.
 
@@ -98,6 +149,33 @@ When multiple teams share a Namespace, prefix each Workflow ID with a service-sp
 Task Queue names must also be unique within the Namespace.
 :::
 
+### Pattern 4: Namespace per tenant
+
+Use a separate [Namespace](/namespaces) per tenant only when each tenant needs a true isolation boundary.
+
+This is usually appropriate only for a small number of high-value tenants that require:
+
+- dedicated credentials and access control
+- tenant-specific rate limits or capacity decisions
+- strict compliance or data-isolation boundaries
+- independent debugging, alerting, and operational ownership
+
+For most SaaS use cases, a shared Namespace with per-tenant [Task Queues](/task-queue) is simpler and more scalable.
+See [Multi-tenant application patterns](/production-deployment/multi-tenant-patterns) for those designs.
+
+### What should cause you to split a Namespace later?
+
+Revisit your topology when one or more of the following becomes true:
+
+- one workload is consuming enough APS that it regularly threatens others in the same Namespace
+- one team needs tighter access controls or dedicated credentials
+- production troubleshooting requires clearer dashboards, alerts, or ownership boundaries
+- one application or domain is business-critical enough that its blast radius must be reduced
+- a tenant or regulated workload needs stronger separation than Task Queue isolation can provide
+
+Splitting a Namespace increases safety, but it also adds overhead for provisioning, tagging, credentials, and cross-Namespace coordination.
+Use [Nexus](/nexus) where possible instead of sharing Temporal primitives across team or domain boundaries.
+
 ## Production Safeguards
 
 ### Use an Authorizer (open source only) {#authorizer}

docs/cloud/get-started/api-keys.mdx

@@ -57,6 +57,9 @@ The authentication process follows this pathway:
   unexpected or unauthorized activity.
 - **Use a Key Management System (KMS)**: Employ a Key Management System to minimize the risk of key leaks.
 
+For guidance on which identities should own API keys, when to use Namespace-scoped Service Accounts, and how to align
+API keys with your Namespace topology, see [Managing Temporal Cloud access control](/best-practices/cloud-access-control).
+
 ### API key use cases
 
 API keys are used for the following scenarios:
@@ -223,6 +226,9 @@ Temporal API keys automatically expire based on the specified expiration time. F
 1. Switch clients to load the new key and start using it.
 1. Delete the old key after it is no longer in use.
 
+For a broader machine-identity rotation strategy across API keys and Service Accounts, see
+[Managing Temporal Cloud access control](/best-practices/cloud-access-control).
+
 ## Manage API keys for Service Accounts {#serviceaccount-api-keys}
 
 Global Administrators and Account Owners can manage and generate API keys for _all_ Service Accounts in their account.

docs/cloud/get-started/namespaces.mdx

@@ -236,77 +236,11 @@ See the [`tcld` namespace create](/cloud/tcld/namespace/#create) command referen
 
 ## What are some Namespace best practices? {#best-practices}
 
-This section provides general guidance for organizing [Namespaces](/namespaces) across use cases, services,
-applications, or domains. Temporal Cloud provides Namespace–as-a-service, so the Namespace is the endpoint. Customers
-should consider not only a Namespace naming convention but also how to group or isolate workloads using the Namespace as
-a boundary.
+For guidance on how many Namespaces to create, how to split workloads across services or domains, and when to isolate
+tenants or teams, see [Namespace best practices](/best-practices/managing-namespace).
 
-Each team can have their own Namespace for improved modularity, security, debugging, and fault isolation. Namespaces
-contain the blast radius of misbehaving Workers that may exhaust rate limits. Sensitive Workflow state (PCI data) can be
-secured with per-Namespace permissions and encrypted with a separate encryption key.
-
-Temporal Applications in different Namespaces may be connected with [Nexus](/cloud/nexus) by exposing a clean service
-contract for others to use with built-in [Nexus access controls](/cloud/nexus/security). Nexus supports cross-team,
-cross-domain, multi-region, and multi-cloud use cases.
-
-### Constraints and limitations
-
-Before considering an appropriate Namespace configuration, you should be aware of the constraints 
-listed on the [Temporal Cloud Limits](/cloud/limits) page. 
-
-For advice on managing Namespaces within limits, see the [Namespace Best Practices](/best-practices/managing-namespace) page.
-
-### General guidance
-
-Namespace configuration requires some consideration. Following are some general guidelines to consider.
-
-- Namespaces are usually defined per use case. A use case can encompass a broad range of Workflow types and a nearly
-  unlimited scale of concurrent [Workflow Executions](/workflow-execution). 
-- Namespaces can be split along additional boundaries such as service, application, domain or even sub-domain.
-- Namespaces should be used to reduce the "blast radius" for mission-critical applications.
-- Environments such as production and development usually have requirements for isolation. We recommend that each
-  environment has its own Namespace.
-- Namespaces should be used to reduce the "blast radius" for mission-critical applications.
-- Use [Nexus](/nexus) to communicate across team, domain, and Namespace boundaries with a clean service contract instead of sharing Temporal primitives directly.
-  Nexus enables each team to have their own Namespace for improved security, troubleshooting, and fault isolation while sharing capabilities through Nexus Endpoints.
-
-### Examples
-
-Following are some ideas about how to organize Namespaces.
-
-#### Example 1: Namespace per use case and environment
-
-We recommend using one Namespace for each use case and environment combination for simple configurations in which
-multiple services and team or domain boundaries don't exist.
-
-Sample naming convention:
-
-<pre>&lt;use-case>_&lt;environment></pre>
-
-#### Example 2: Namespace per use case, service, and environment
-
-We recommend using one Namespace for each use case, service, and environment combination when multiple services that are
-part of same use case communicate externally to Temporal via API (HTTP/gRPC).
-
-Sample naming convention:
-
-<pre>&lt;use-case>_&lt;service>_&lt;environment></pre>
-
-#### Example 3: Namespace per use case, domain, and environment
-
-We recommend using one namespace per use case, domain, and environment combination when multiple services that are part
-of the same use case need to communicate with each another via [Signals](/sending-messages#sending-signals) or by
-starting [Child Workflows](/child-workflows). In this case, though, you must be mindful about Workflow Id uniqueness by
-prefixing each Workflow Id with a service-specific string. The name of each Task Queue must also be unique. If multiple
-teams are involved, the domain could also represent a team boundary.
-
-Sample naming convention:
-
-<pre>&lt;use-case>_&lt;domain>_&lt;environment></pre>
-
-Sample workflowId convention:
-
-<pre>&lt;service-string>_&lt;workflow-id></pre>
+This page focuses on Temporal Cloud namespace mechanics such as naming rules, provisioning, authentication, tagging, and
+accessing Namespace endpoints.
 
 ## How to access a Namespace in Temporal Cloud {#access-namespaces}