# Managing Temporal Cloud access control

> Best practices for managing access control, permissions, and user management in Temporal Cloud.

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](/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
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:
- https://docs.temporal.io/cloud/certificates#manage-certificates 
- https://docs.temporal.io/cloud/api-keys#rotate-an-api-key 
- https://github.com/temporal-sa/temporal-Worker-cert-rotation 

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](https://openssl-library.org/), [CFSSL](https://github.com/cloudflare/cfssl), or [step CLI](https://github.com/smallstep/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](https://docs.temporal.io/cloud/certificates#control-authorization) of the documentation. 

## 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, 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:

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.