# Namespaces

> **ℹ️ Info:**
> Temporal Cloud
> This page covers namespace operations in **Temporal Cloud**.
> For core namespace concepts, see [Temporal Namespace](/namespaces).
> For open source Temporal, see [Managing Namespaces](/self-hosted-guide/namespaces).

A Namespace is a unit of isolation within Temporal Cloud, providing security boundaries, Workflow management, unique
identifiers, and gRPC endpoints in Temporal Cloud.

- [Create a Namespace](#create-a-namespace)
- [Access a Namespace](#access-namespaces)
- [Manage Namespaces](#manage-namespaces)
- [Delete a Namespace](#delete-a-namespace)
- [Tag a Namespace](#tag-a-namespace)

## What is a Cloud Namespace Name? 

A Cloud Namespace Name is a customer-supplied name for a [Namespace](/namespaces) in Temporal Cloud. Each Namespace
Name, such as `accounting-production`, is unique within the scope of a customer's account. It cannot be changed after
the Namespace is provisioned.

Each Namespace Name must conform to the following rules:

- A Namespace Name must contain at least 2 characters and no more than 39 characters.
- A Namespace Name must begin with a letter, end with a letter or number, and contain only letters, numbers, and the
  hyphen (-) character.
- All letters in a Namespace Name must be lowercase.

> **📝 Note:**
> The Namespace Name alone is not sufficient to connect to or reference a Namespace. All Temporal Cloud operations — SDK connections, CLI commands, and API calls — require the full **Namespace ID**, which combines your Namespace Name with your Account ID:
>
> `<namespace-name>.<account-id>`
>
> For example: `accounting-production.123de`
>
> The full Namespace ID is shown in the Namespace list in the Temporal Cloud UI and in the output of `tcld namespace list`. See [Cloud Namespace ID](#temporal-cloud-namespace-id) for details.

## What is a Temporal Cloud Account ID? 

A Temporal Cloud Account ID is a unique customer identifier assigned by Temporal Technologies. Each Id is a short string
of numbers and letters like `f45a2`, at least five characters long. This account identifier is part of every Namespace ID
in your account and is retained while you use Temporal Cloud.

You can retrieve your Account ID from the [Temporal Cloud](https://cloud.temporal.io) Web UI or by using the `tcld`
utility at a command line interface (CLI). Follow these steps.

**Web UI**

    Follow these steps to retrieve your Account ID:

    1. Log into Temporal Cloud.
    1. Select your account avatar at the top right of the page.
       A profile dropdown menu appears.
    1. Copy the Cloud Account ID from the menu.
![Temporal Cloud user profile dropdown menu. The dropdown includes a Cloud Account ID and copy button, with role, profile and logout options, and links to community resources.](/img/cloud/cloud-guide/cloud-account-id.png)

    In this example, the Account ID is `123de`.

**tcld**

    1. Use the `tcld` utility to log into an account.

       ```
       tcld login
       ```

       The `tcld` output presents a URL with an activation code at the end. Take note of this code. The utility blocks until the login/activation process completes.

       ```
       Login via this url: https://login.tmprl.cloud/activate?user_code=KTGC-ZPWQ
       ```

       A Web page automatically opens for authentication in your default browser.

    1. Visit the browser.
       Ensure the user code shown by the CLI utility matches the code shown in the Web browser.
       Then, click Confirm in the browser to continue.
       After confirmation, Web feedback lets you know that the CLI "device" is now connected.

    1. Return to the command line.
       Issue the following command.

       ```
       tcld namespace list
       ```

       The CLI tool returns a short JSON packet with your namespace information.
       This is the same list found in the Temporal Cloud Web UI Namespaces list.
       Like the browser version, each Namespace uses an Account ID suffix.

       ```
       {
         "namespaces": [
           "your-namespace.123de",
           "another-namespace.123de"
         ],
         "nextPageToken": ""
       }
       ```

    Each Namespace automatically appends an Account ID suffix to its customer-supplied identifier.
    This five-character-or-longer string appears after the name, separated by a period.
    In this Namespace listing sample, the Account ID is 123de.

## What is a Cloud Namespace Id? 

A Cloud Namespace Id is a globally unique identifier for a [Namespace](/namespaces) in Temporal Cloud. A Namespace Id is
formed by concatenating the following:

1. A [Namespace Name](#temporal-cloud-namespace-name)
1. A period (.)
1. The [Account ID](#temporal-cloud-account-id) to which the Namespace belongs

For example, for the Account ID `123de` and Namespace Name `accounting-production`, the Namespace Id is
`accounting-production.123de`.

## What is a Cloud gRPC Endpoint? 

Temporal Clients communicate between application code and a Temporal Server by sending and receiving messages via the
gRPC protocol. gRPC is a Remote Procedure Call framework featuring low latency and high performance. gRPC provides
Temporal with an efficient, language-agnostic communication framework.

Every Temporal Namespace uses a gRPC endpoint for communication. When migrating to Temporal Cloud, you'll need to switch
the gRPC endpoint in your code from your current hosting, whether self-hosted or locally-hosted, to Temporal Cloud.

A gRPC endpoint appears on the detail page for each Cloud Namespace. Follow these steps to find it:

1. Log into your account on [cloud.temporal.io](https://cloud.temporal.io/namespaces).
2. Navigate to the Namespace list page from the left-side vertical navigation.
3. Tap or click on the Namespace Name to select and open the page for the Namespace whose endpoint you want to retrieve.
4. On the Namespace detail page, click on the "Connect" button in the top right corner of the page.
5. Click the copy icon next to the gRPC address to copy it to your clipboard.

See [How to access a Namespace in Temporal Cloud](/cloud/namespaces/#access-namespaces) for more information on
different gRPC endpoint types and how to access them.

## How to create a Namespace in Temporal Cloud 

> **ℹ️ Info:**
>
> The user who creates a [Namespace](/namespaces) is automatically granted
> [Namespace Admin](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) permission for that Namespace.
>
> To create a Namespace, a user must have the Developer, Account Owner, or Global Admin account-level
> [Role](/cloud/manage-access/roles-and-permissions#account-level-roles).
>

> **💡 Tip:**
>
> By default, each account starts with 10 Namespaces. This limit increases automatically when your existing Namespaces have scheduled or running Workflow Executions. For large-scale needs, open a [support ticket](/cloud/support#support-ticket).
>

### Information needed to create a Namespace

To create a Namespace in Temporal Cloud, gather the following information:

- [Namespace Name](/cloud/namespaces#temporal-cloud-namespace-name), region, and Cloud Provider
- [Retention Period](/temporal-service/temporal-server#retention-period) for the
  [Event History](/workflow-execution/event#event-history) of closed [Workflow Executions](/workflow-execution).
- [CA certificate](/cloud/certificates#certificate-requirements) for the Namespace, if you are using mTLS
  authentication.
- [Codec Server endpoint](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli) to
  show decoded payloads to users in the Event History for Workflow Executions in the Namespace. For details, see
  [Securing your data](/production-deployment/data-encryption).
- [Permissions](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) for each user.

**Web UI**

### Create a Namespace using Temporal Cloud UI

1. Gather the information listed earlier in
   [Information needed to create a Namespace](#information-needed-to-create-a-namespace).
1. Go to the Temporal Cloud UI and log in.
1. On the left side of the window, click **Namespaces**.
1. On the **Namespaces** page, click **Create Namespace** in the upper-right portion of the window.
1. On the **Create Namespace** page in **Name**, enter the Namespace Name.
1. In **Cloud Provider**, select the cloud provider in which to host this Namespace.
1. In **Region**, select the region in which to host this Namespace.
1. In **Retention Period**, specify a value from 1 to 90 days. When choosing this value, consider your needs for Event
   History versus the cost of maintaining that Event History. Typically, a development Namespace has a short retention
   period and a production Namespace has a longer retention period. The retention period of a namespace can be changed
   in the Temporal Cloud UI under the namespace's Settings tab or by using the Temporal CLI.
1. Select your authentication method: [API keys](/cloud/api-keys) or [mTLS](/cloud/certificates).
1. If using mTLS authentication, paste the CA certificate for this Namespace.
1. Optional: In **Codec Server**, enter the HTTPS URL (including the port number) of your Codec Server endpoint. You may
   also enable "Pass the user access token with your endpoint" and "Include cross-origin credentials." For details, see
   [Hosting your Codec Server](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli).
1. Click **Create Namespace**.

**tcld**

See the [`tcld` namespace create](/cloud/tcld/namespace/#create) command reference for details.

## What are some Namespace best practices? 

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

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 

Temporal Cloud supports authentication to Namespaces using [API keys](/cloud/api-keys) _or_
[mTLS](/cloud/certificates). To migrate a Namespace from one authentication method to another, or to use both API
key and mTLS authentication on the same Namespace, please contact
[Support](https://docs.temporal.io/cloud/support#support-ticket).

> **ℹ️ Info:**
>
> Using **both** API key and mTLS authentication on the **same** Namespace is in
> [pre-release](/evaluate/development-production-features/release-stages) and doesn't support
> [High Availability features](/cloud/high-availability) or authenticating with an API Key to a Namespace Endpoint.
>

Connecting to your Namespace requires a specific endpoint that works for the given Namespace.
There are two types of gRPC endpoints for accessing a Namespace in Temporal Cloud: a Namespace endpoint and a regional endpoint.

- **Namespace endpoint** (`<namespace>.<account>.tmprl.cloud:7233`) — **Recommended**
    - This endpoint is unique to each Namespace. It always connects to the Namespace, no matter which region(s) the Namespace is using.
    - A Temporal Client that uses a Namespace endpoint doesn't have to be aware of which region the Namespace is in.
    - For Namespaces with [High Availability](/cloud/high-availability), the Namespace endpoint automatically directs traffic to the active region, so Workers and Clients don't need to change endpoints during a failover.
- Regional endpoint (`<region>.<cloud_provider>.api.temporal.io:7233`)
    - Temporal Cloud has only one regional endpoint for each cloud region. The same regional endpoint can access any Namespace that is active in that region (or that has a [replica](/cloud/high-availability) in that region).
    - A Temporal Client can use a regional endpoint to ensure connection to a Namespace always happens within that region. This can be useful in advanced [High Availability](/cloud/high-availability) setups where you want explicit control over which region handles requests.
    - When using mTLS to authenticate, the Temporal Client must set the `server_name` property to `<namespace endpoint value>` in its request to the value of the Namespace endpoint. This tells the client to expect a different SNI header during the TLS handshake, since the request to the regional endpoint is redirected to the specific Namespace.

> **⚠️ Caution:**
> Do not take dependencies on Temporal Cloud endpoint DNS resolution
>
> In general, the IP addresses that Temporal Cloud endpoints resolve to are subject to change without notice. Do not configure Workers, Temporal Clients, or firewalls against the specific IPs you observe for an endpoint at a point in time.
>
> Temporal Cloud guarantees the DNS resolution behavior of the Namespace Endpoint in two cases:
>
> 1. **Stable IPs enabled.** The Namespace Endpoint resolves to one of the [Stable IPs](/cloud/connectivity/ip-addresses) for the Namespace's active region.
> 2. **High Availability features with Private Connectivity.** The Namespace Endpoint resolves to a regional intermediary (`<provider>-<region>.region.tmprl.cloud`) that you can override in a Route 53 private hosted zone or GCP private DNS zone to point at your VPC Endpoint. See [Connectivity for High Availability](/cloud/high-availability/ha-connectivity) for setup details.
>

### Configuring a Temporal Client with API keys or mTLS

To use API keys to connect with the [Temporal CLI](/cli), [Client SDK](/develop), [tcld](/cloud/tcld),
  [Cloud Ops API](/ops), and [Terraform](/cloud/terraform-provider), see
  [Use API keys to authenticate](/cloud/api-keys#using-apikeys).

To use mTLS to connect with the [Temporal CLI](/cli) and [Client SDK](/develop), see
  [Configure Clients to use Client certificates](/cloud/certificates#configure-clients-to-use-client-certificates).

### Accessing the Temporal Web UI

For accessing the Temporal Web UI, use the HTTPS endpoint in the form:
`https://cloud.temporal.io/namespaces/<namespace>.<account>`. For example:
`https://cloud.temporal.io/namespaces/accounting-production.f45a2`.

### Accessing Namespaces with Encryption and Private Connectivity

To ensure the security of your data, all traffic to and from your Namespace is encrypted with TLS 1.3. 

For enhanced protection:
- Set up [private connectivity](/cloud/connectivity#private-network-connectivity-for-namespaces) to the Namespace.
- Set up your allow list for outgoing network requests from your Clients and Workers. You have two options:
  - Use Temporal Cloud's [stable IPs configuration](/cloud/connectivity/ip-addresses) to get non-changing IP addresses for your Namespace endpoint, which you can then allowlist in your firewall rules.
  - Allowlist the entire Cloud Provider IP address ranges for the region in which your Namespace is located:
    - [AWS IP address ranges](https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html)
    - [GCP IP address ranges](https://cloud.google.com/compute/docs/faq#find_ip_range)

## How to manage Namespaces in Temporal Cloud 

### Manage Namespaces in Temporal Cloud using Temporal Cloud UI

To list Namespaces:

- On the left side of the window, select **Namespaces**.

To edit a Namespace (including custom Search Attributes, certificates, certificate filters, Codec Server endpoint,
permissions, and users), find the Namespace and do either of the following:

- On the right end of the Namespace row, select the three vertical dots (⋮). Click **Edit**.
- Select the Namespace name. In the top-right portion of the page, select **Edit**.

On the **Edit** page, you can do the following:

- Add a [custom Search Attribute](/search-attribute#custom-search-attribute).
- [Manage CA certificates](/cloud/certificates).
- [Manage certificate filters](/cloud/certificates#manage-certificate-filters-using-temporal-cloud-ui).
- Set
  [Codec Server endpoint](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli)
  for all users on the Namespace. Each user on the Namespace has the option to
  [override this setting](/production-deployment/data-encryption#web-ui) in their browser.
- Manage [Namespace-level permissions](/cloud/manage-access/roles-and-permissions#namespace-level-permissions).
- Add users.

To add a user to a Namespace, scroll to the bottom of the page and select **Add User**.

After you make changes, select **Save** in the top-right or bottom-left portion of the page.

### Manage Namespaces in Temporal Cloud using tcld

To list Namespaces and get information about them, use the following [tcld](/cloud/tcld/) commands:

- [tcld namespace list](/cloud/tcld/namespace/#list)
- [tcld namespace get](/cloud/tcld/namespace/#get)

To manage certificates, use the [tcld namespace accepted-client-ca](/cloud/tcld/namespace/#accepted-client-ca) commands.
For more information, see [How to manage certificates in Temporal Cloud](/cloud/certificates).

To manage certificate filters, use the [tcld namespace certificate-filters](/cloud/tcld/namespace/#certificate-filters)
commands. For more information, see
[How to manage certificate filters in Temporal Cloud](/cloud/certificates#manage-certificate-filters).

## How to delete a Namespace in Temporal Cloud 

> **ℹ️ Info:**
>
> To delete a Namespace, a user must have Namespace Admin [permission](/cloud/manage-access/roles-and-permissions#namespace-level-permissions) for that
> Namespace.
>

### Delete a Namespace using Temporal Cloud UI

1. Go to the Temporal Cloud UI and log in.
1. On the left side of the window, select **Namespaces**.
1. On the **Namespaces** page, select a Namespace Name.
1. On the Namespace page, select **Edit** in the upper-right portion of the window.
1. On the **Edit** Namespace page, select **Delete Namespace** in the upper-right portion of the window.
1. In the **Delete Namespace** dialog, type `DELETE` to confirm the deletion of that Namespace.
1. Select **Delete**.

After deleting a Temporal Cloud Namespace, the Temporal Service immediately removes the Namespace's Workflow Executions
and Task Queues. Make sure all Workflows have been completed, canceled, or terminated before removing a Namespace. The
Namespace removal is permanent.

Closed Workflow Histories remain in Temporal storage until the user-defined retention period expires. This period
reflects the policy in effect when the Workflow Execution was closed.

For further questions or concerns, contact [Support](https://docs.temporal.io/cloud/support#support-ticket).

### Delete a Namespace using tcld

See the [tcld namespace delete](/cloud/tcld/namespace/#delete) command reference for details.

### Namespace deletion protection 

To prevent accidental Namespace deletion, Temporal Cloud provides a protection feature. When you enable Deletion
Protection for your production environment Namespace, you ensure that critical data won't be deleted unintentionally.

Follow these steps:

- Visit the [Namespaces page](https://cloud.temporal.io/namespaces) on Temporal Cloud.
- Open your Namespace details page.
- Select the Edit button.
- Scroll down to Security and click the disclosure button (downward-facing caret).
- Enable **Deletion Protection**

![Deletion Protection is enabled by toggling the switch](/img/cloud/namespace/deletion-protection.png)

To enable or disable this feature using [`tcld`](/cloud/tcld), use the following command. Set the value to `true` to
enable or `false` to disable:

```
tcld namespace lifecycle set \
    --namespace <namespace_id.account_id> \
    --enable-delete-protection <Boolean>
```

## How to tag a Namespace in Temporal Cloud 

Tags are key-value metadata pairs that can be attached to namespaces in Temporal Cloud to help operators organize,
track, and manage namespaces more easily.

### Tag Structure and Limits

- Each namespace can have a maximum of 10 tags
- Each key must be unique for a given namespace (e.g., a namespace cannot have both `team:foo` and `team:bar` tags)
- Keys and values must be 1-63 characters in length
- Allowed characters: lowercase letters (`a-z`), numbers (`0-9`), periods (`.`), underscores (`_`), hyphens (`-`), and
  at signs (`@`)
- Tags are not a secure storage mechanism and should not store PII or PHI
- Tags will not change the behavior of the tagged resource
- There is a soft limit of 1000 unique tag keys per account

### Permissions

- Only [**Account Admins** and **Account Owners**](/cloud/manage-access/roles-and-permissions#account-level-roles) can create and edit tags
- All users with access to a namespace can view its tags

### tcld

See the [tcld namespace tags](/cloud/tcld/namespace/#tags) command reference for details.

### Terraform

See the
[Terraform provider](https://github.com/temporalio/terraform-provider-temporalcloud/blob/main/docs/resources/namespace_tags.md)
for details.

### Web UI

Tags can be viewed and managed through the Temporal Cloud web interface. When viewing a namespace, you'll see tags
displayed and can add, edit, or remove them if you have the appropriate permissions.

![Tags appear in namespace details](/img/cloud/tags/Namespace-DetailsWithTags.png)

![Tags appear on the list of namespaces](/img/cloud/tags/Namespaces-IndexWithTags.png)

![Where to add tags during namespace creation](/img/cloud/tags/CreateNamespace-AddNewTag.png)

![After adding a tag during namespace creation](/img/cloud/tags/CreateNamespace-AddedTag.png)