Skip to main content

Managing Temporal Cloud access control

Temporal Cloud supports two secure authentication methods for Workers:

  • mTLS Certificates
  • API Keys (configured via the UI when creating a namespace)

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 and Manage service accounts.

Related guidance:

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
  2. Support dual credentials: Update Temporal Cloud to support both old and new credentials
  3. Migrate Workers: Transition Worker applications from old credentials to new credentials
  4. Validate connectivity: Confirm all Workers can authenticate, and business processes operate normally with new credentials
  5. Remove old credentials: Remove old certificates and API keys from your secrets provider after confirming successful migration

This approach ensures near-zero-downtime rotation and prevents authentication failures that could impact running workflows. For specific guidance to rotate mTLS certificates and API keys, see:

For mutual TLS (mTLS) implementations, using Let's Encrypt is not recommended, as it is designed primarily for public-facing services and lacks support for internal certificate requirements.

While we are not making a specific product recommendation, there are several valid options for managing certificates. Many organizations choose vendor solutions such as AWS Private CA, Sectigo, Microsoft Certification Authority, or DigiCert for their robust integration and lifecycle features. Alternatively, self-signed certificates are a valid and commonly used approach, even in production environments. If you choose to self-sign, tools like OpenSSL, CFSSL, or step CLI can help generate and manage certificates effectively.

Select the option that aligns best with your infrastructure, security requirements, and operational needs.

In the case that you are using multiple certificates signed by the same CA, and some of these certificates are for production environments, there are some workarounds you can employ.

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 of the documentation.

Best practices​

Establish clear guidelines on authentication methods​

Teams should standardize on either mTLS certificates or API keys for the following operations:

By default, it is recommended for teams to use API keys and 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.

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 and Terraform provider only supports API key for authentication).

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 and Multi-tenant application patterns.

Rotate credentials without downtime​

Use the following sequence when rotating credentials:

  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.

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.

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.