# Namespace best practices

> Best practices for organizing and managing Temporal Namespaces, including naming conventions, organizational patterns, and production safeguards.

> **ℹ️ Info:**
> Applies to both open source and Temporal Cloud
> This page covers namespace best practices that apply to **both** open source Temporal and Temporal Cloud.
> Platform-specific guidance is clearly labeled throughout.
>
> For reference documentation, see:
> - [Namespace concepts](/namespaces)
> - [Managing Namespaces (open source)](/self-hosted-guide/namespaces)
> - [Namespaces (Temporal Cloud)](/cloud/namespaces)

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

Use lowercase letters and hyphens (`-`) as separators in Namespace names.

- **Temporal Cloud**: Namespace names are case-insensitive, so `MyNamespace` and `mynamespace` refer to the same Namespace.
- **Open source**: Namespace names are case-sensitive, so `MyNamespace` and `mynamespace` are different Namespaces.

To avoid confusion across environments, always use lowercase.

**Example**: `payment-checkout-prd`

### Follow a consistent naming pattern

Use a pattern like `<use-case>-<domain>-<environment>` to name Namespaces:

| Component | Max Length | Examples |
|-----------|------------|----------|
| Use case | 10 chars | `payments`, `fulfill`, `orders` |
| Domain | 10 chars | `checkout`, `notify`, `inventory` |
| Environment | 3 chars | `dev`, `stg`, `prd` |

**Examples**: `payments-checkout-dev`, `fulfill-notify-prd`, `orders-inventory-stg`

**Why this pattern?**
- Simple and easy to understand
- Clearly separates environments
- Groups related services under domains
- Allows platform teams to implement chargeback to application teams
- Namespace-level limits are isolated between different services and environments

> **💡 Tip:**
> Temporal Cloud
> Cloud Namespace names are limited to [39 characters](/cloud/namespaces#temporal-cloud-namespace-name).
> 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>`

**Example**: `payments-prd`, `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>`

**Example**: `payments-gateway-prd`, `payments-processor-prd`

Choose this pattern when:

- 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>`

**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.

> **📝 Note:**
> Workflow ID uniqueness
> When multiple teams share a Namespace, prefix each Workflow ID with a service-specific string to ensure uniqueness.
> 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) 

Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Frontend Service to set restrictions on who can create, update, or deprecate Namespaces.

If an Authorizer is not set, Temporal uses the `nopAuthority` authorizer that unconditionally allows all API calls.

On Temporal Cloud, [role-based access controls](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) provide namespace-level authorization without custom configuration.

### Enable deletion protection (Temporal Cloud only) 

[Enable deletion protection](/cloud/namespaces#delete-protection) for production Namespaces to prevent accidental deletion.

### Enable High Availability (Temporal Cloud only) 

For business-critical use cases with strict uptime requirements, enable [High Availability features](/cloud/high-availability) for a [99.99% contractual SLA](/cloud/high-availability#high-availability-features).

### Use Infrastructure as Code (Temporal Cloud only) 

Use the [Temporal Cloud Terraform provider](/cloud/terraform-provider) to manage Namespaces.
If Terraform isn't suitable, scripting against the [Cloud Ops API](/ops) or [tcld](/cloud/tcld) is a good alternative.

This provides:
- Documentation of each Namespace's purpose and owners
- Prevention of infrastructure drift
- Version-controlled configuration changes

Use `prevent_destroy = true` in your Terraform configuration to prevent accidental Namespace deletion via Terraform.
This is separate from [Temporal Cloud deletion protection](/cloud/namespaces#delete-protection), which prevents deletion through any interface.

**Reference**: [Example Terraform configuration](https://github.com/kawofong/temporal-terraform)

## Tagging (Temporal Cloud only) 

[Tags](/cloud/namespaces#tag-a-namespace) are key-value metadata pairs that help organize, track, and manage Namespaces.

Tags complement your naming convention by adding metadata that doesn't fit in the Namespace name.
While the name captures use case, domain, and environment, tags can capture additional dimensions like team ownership, data sensitivity, or business criticality.

### Recommended tag categories

| Tag Key | Purpose | Examples |
|---------|---------|----------|
| `environment` | Deployment stage | `dev`, `staging`, `production` |
| `team` | Owning team | `platform`, `payments`, `identity` |
| `division` | Business unit | `engineering`, `finance`, `ops` |
| `criticality` | Business importance | `high`, `medium`, `low` |
| `data-sensitivity` | Data classification | `pii`, `pci`, `public` |
| `latency-sensitivity` | Performance tier | `realtime`, `batch`, `async` |

For tag structure, limits, and management instructions, see [How to tag a Namespace](/cloud/namespaces#tag-a-namespace).

## SDK Client Configuration

Set Namespaces in your SDK Client to isolate your Workflow Executions.
If you do not set a Namespace, all Workflow Executions started using the Client will be associated with the `default` Namespace.

You must register a Namespace before setting it in your Client.

For configuration details, see:
- [Namespace concepts](/namespaces)
- [Namespaces (Temporal Cloud)](/cloud/namespaces#access-namespaces)