---
title: Website channel management
related:
  - https://docs.kentico.com/documentation/developers-and-admins/configuration/website-channel-management/manage-multiple-websites.md
  - https://docs.kentico.com/documentation/developers-and-admins/configuration/administration-domain-configuration.md
  - https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Website channels encapsulate websites managed by Xperience. Each channel is an independent entity with one or more configured domains and content management.

Channels store content in [pages](https://docs.kentico.com/documentation/business-users/website-content.md) and [linked content items](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#link-content-items). See the [content modeling guide](https://docs.kentico.com/guides/architecture/content-modeling/content-modeling-guide.md) to learn more about the recommended ways to store and display content in Xperience.

## Create website channels

To create a new website channel:

1. Open the **Channel management** application in the Xperience administration.

2. Select **New channel**.

3. Fill in:
   - **Channel name** – the name of the channel displayed in the administration. Also sets the name of the channel application where users manage the website's pages and edit content.
   - _(Optional)_ **Identifiers** – specify the code name if you wish to use a code name different than the pre-filled value.
     - Channel code names must be unique across all channels (of any type).
     - In projects intended for [SaaS deployment](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md) (created with the `--cloud` parameter), only code names with alphanumeric characters are allowed.
   - **Channel type** – select _Website_ as the channel type.
   - **Channel size** – channels are available in two sizes: _Standard_ and _Micro_. **Standard** channels may contain an unlimited number of content items. **Microchannels** are limited to 20 items in the channel's page tree (including both standard pages and other items like folders or navigation menu structure). Each page can link an unlimited number of [reusable content items](https://docs.kentico.com/documentation/business-users/content-hub.md).

4. Select the **URL format for multilingual sites**:

> **Warning:** **URL format changes limitations**
>
> Once the channel is created, the URL format can be changed only via the provided CLI tool. The tool is intended to be used before the site goes live. Switching the format is **not supported for live production sites**.

- **Language prefix** – The URLs for all languages share the same domain. The language code is added as a prefix to the URL path to differentiate between language variants of a page. Pages in the primary language (selected later) have no prefix. Example URLs:
  - `mydomain.com/page` for the primary language
  - `mydomain.com/fr-fr/page` for French
- **Domain per language** – Sets the URL format to language-specific domains. Each language therefore uses a different domain in its URLs. The domains are [configured](#configure-language-specific-domains) in the application settings file. Not supported for SaaS projects yet. For example:
  - `mydomain.com/page` for English
  - `mydomain.fr/page` for French

5. If you selected the **Language prefix** URL format for multilingual sites, configure the following settings:

   - **Website domain** – the domain name on which the website will be accessible. See [Website channels in private cloud environments](#website-channels-in-private-cloud-environments) to learn about the expected format and limitations when setting website domains.
   - **Primary language** – a language configured in the **Languages** application. In multilingual content, the primary language is not displayed in URLs, as opposed to other languages. For example: If the primary language is set to English, and content is also in French, the URLs are in the format:
     - `~/page` for English
     - `~/fr-fr/page` for French

6. **Save** the changes.

The website channel is now created. After you add a channel, the system automatically creates a new application matching the channel's name in the **Channels** category of the administration's application list. This is the application where users can create and edit the channel's [pages](https://docs.kentico.com/documentation/business-users/website-content.md).

> **Note:** **Next steps**
>
> Depending on your project set-up, further configuration might be required:
>
> - For applications [deployed in the SaaS environment](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md), you also need to add the channel in Xperience Portal. See [Website channels in the SaaS environment](#website-channels-in-the-saas-environment).
> - If you selected the language-specific domains URL format, ensure that each language has a properly configured domain in the application settings file.

### Configure website channels

If you need to configure an existing channel, open the channel again via the **Channel management** application and edit the values on the **General** and **Channel settings** tabs.

Changing the **Primary language** affects the live URLs of the website's pages in the given languages, and breaks page links added in the [Rich text editor](https://docs.kentico.com/documentation/business-users/rich-text-editor.md).

Use the **Home page** setting on the **Channel settings** tab to select the page served under the channel's root URL (e.g., _https://example.com/_). Without it, the root URL returns a 404 error. You don't need custom routes or middleware to handle the site root – the **Home page** setting covers it. See [Home page redirect and the website root URL](https://docs.kentico.com/documentation/developers-and-admins/development/routing/content-tree-based-routing/enable-content-tree-based-routing.md#home-page-redirect-and-the-website-root-url).

### Change channel size of existing channels

You can freely change between the _microchannel_ and _standard_ channel size of existing channels via the **General** tab. Additionally, changing _standard_ channels to _microchannels_ does not cause any data loss in case the converted channel exceeds microchannel limits. However, you will receive a license violation warning if the resulting channel or item count oversteps the limits of your license for that particular channel type.

## Add allowed content types

Every page in Xperience uses a specific [content type](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md). The content type defines the fields that users can edit when creating pages.

To create pages under a channel, you need to prepare suitable [content types](https://docs.kentico.com/documentation/developers-and-admins/development/content-types.md) and allow them for the channel:

1. Open the **Channel management** application in Xperience.
2. Select your website channel.
3. On the **Allowed content types** tab, **Select content types**.
4. Select or clear the checkboxes to choose which content types you want to make available in the channel.
5. Select **Save**.

### Configure content types users can use

You can granularly limit the content types users can use to create pages for each page, folder, and content type within a given website channel. See [Limit the pages users can create](https://docs.kentico.com/documentation/developers-and-admins/development/content-types/limit-the-pages-users-can-create.md) for more information.

## Website channels in private cloud environments

Depending on the selected URL format, a website channel can either use one main domain for all languages, or a separate domain for each language. Each domain assigned to a channel has to be unique within the system. The configured domain or domains determine where the live website is accessible. The system also uses the corresponding domain when displaying previews of live content, resolving hyperlinks in text, and for other use cases.

### Domain name format

Use the following format for the domain names:

- include the port number if the application is running under a different port than _80_
- do not include the URL scheme (protocol) – both _http_ and _https_ are included automatically
- include the path in the URL if your site is running under a specific path, for example, _mysite.com/path_

**Incorrect domain name**:

- https://mysite.com

**Correct domain names**:

- mysite.com
- partners.mysite.com
- mysite.com:8080
- mysite.com/path

### Configure a domain name in the Xperience administration

> **Note:** Applies only to channels using the language prefix URL format. For [language-specific domains](#create-website-channels), see [Configure language-specific domains](#configure-language-specific-domains).

1. Use a domain name conforming to the [domain name format](#domain-name-format).

   > **Info:** To run Xperience in your local development environment, for example on the _localhost_ domain, set **Website domain** to `localhost`.
   >
   > You can configure the system to use a different set of domains according to the project environment. See [Domain aliases and environment-specific domains](#domain-aliases-and-environment-specific-domains).

2. Open the **Channel management** application in the **Xperience administration**.

3. Select the website channel.

4. Switch to the **General** tab.

5. Edit the **Website domain** field.

6. Select **Save**.

The domain name is now registered in the Xperience administration.

### Configure language-specific domains

> **Note:** Applies only to channels using [language-specific domains](#create-website-channels).

When a channel is created with the language-specific domains format, the individual domains then need to be configured programmatically using the `WebsiteChannelDomainOptions` options class and ASP.NET Core [configuration providers](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/). Each language used in the channel needs to have its domain configured to be able to serve content.

For example, when configured via `appsettings.json`:

```json title="appsettings.json"
{
  "WebsiteChannelDomains": {
    "LanguageDomains": {
      "<channel-code-name>": {
        "Domains": {
          "en": [ "dancinggoat.com" ],
          "fr": [ "fr.dancinggoat.com" ],
          "cs": [ "www.dancinggoat.cz"]
        }
      }
    }
  }
}
```

Add the following code to your `Program.cs` to apply the appsettings configuration:

```csharp title="Program.cs"
using CMS.Websites;

var builder = WebApplication.CreateBuilder(args);

// Apply the configuration from appsettings.json
builder.Services.Configure<WebsiteChannelDomainOptions>(builder.Configuration.GetSection("WebsiteChannelDomains"));
```

Each key under `Domains` is the code name of a [content language](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md) associated with the domain configured for that language. Each domain has to be unique. Refer to [Domain name format](#domain-name-format) for the correct format to use.

The configured domains are evaluated on startup. If the same domain is configured for two languages, or when a language that does not exist in the system is included, a warning is logged in the [event log](https://docs.kentico.com/documentation/developers-and-admins/configuration/event-log.md). The system does not check whether all languages in the system have a domain assigned, however, you will be notified in the admin UI when you work on pages in a language that has no domain configured.

You can also configure aliases for each domain – see [Domain aliases and environment-specific domains](#domain-aliases-and-environment-specific-domains).

### Change the URL format for multilingual sites

> **Note:** The URL format of a channel **can be changed before a site goes live**. Switching the format for a live production site is not supported because the change breaks the existing URLs.

Once a channel is created, its URL format cannot be switched in the admin UI. Instead, a provided CLI tool is used for this purpose. The tool changes the URL format setting and adjusts the [existing system page URLs](https://docs.kentico.com/documentation/business-users/website-content/manage-page-urls.md) to conform to the new pattern. Depending on the state of your project, [you might need to perform further adjustments.](#follow-up-steps).

To change the URL format of a channel:

1. If your team uses [Continuous Integration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-integration.md), make sure it is [enabled](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-integration.md#enable-continuous-integration) on your instance so that the URL format change is shared with other instances.

2. Run the command for the direction you're converting to. Use the `--dry-run` parameter to preview the changes that would be carried out by the command – the URL format won't be changed yet.

To change **from URL prefixes to language-specific domains**, run the following command.

```powershell
dotnet run --no-build --kxp-migrate-language-domain-urls --direction to-domain --channel <channel codename> 
```

To change **from language-specific domains to the language prefix format**, run:

```powershell
dotnet run --no-build --kxp-migrate-language-domain-urls --channel <channel codename> --direction to-prefix --primary-language <language codename> --domain <domain name>
```

- `domain` – the domain name on which the website will be accessible. See [Website channels in private cloud environments](#website-channels-in-private-cloud-environments) to learn about the expected format and limitations when setting website domains.
- `primary-language` – code name of a language configured in the **Languages** application. In multilingual content, the primary language is not displayed in URLs, as opposed to other languages. For example: If the primary language is set to English, and content is also in French, the URLs are in the format:
  - `~/page` for English
  - `~/fr-fr/page` for French

If the URL format change would result in a URL collision, the migration stops and the URL format of the channel stays unchanged. Edit the problematic [vanity URLs](https://docs.kentico.com/documentation/business-users/website-content/manage-page-urls.md#edit-vanity-urls-of-pages) or [URL slugs](https://docs.kentico.com/documentation/business-users/website-content/manage-page-urls.md#edit-url-slugs-of-pages) and run the command again.

#### Follow-up steps

After changing the URL format, you might need to perform the following steps:

- If the URL format is now newly set to language-specific domains, [configure the language domains](#configure-language-specific-domains).

- If present, adjust custom code that relies on the selected URL format. Typically, most of the code deals with URLs in the context of one language, so no changes are required there.
  - Review code that provides links from one language to another (for example a language selector that switches between languages on the live site) – it should reflect the language prefix for language prefix mode, or use absolute URLs for language-specific domains.
  - If you use ASP.NET routing on top of the content-tree based routing, make sure the language prefix is inserted for the prefix mode and not present for the language-specific domains mode. See [Set up content tree-based routing](https://docs.kentico.com/documentation/developers-and-admins/development/routing/content-tree-based-routing/set-up-content-tree-based-routing.md#combine-content-tree-based-and-asp.net-routing).
  - For channels that currently use language-specific domains, handle [language fallbacks](https://docs.kentico.com/documentation/developers-and-admins/configuration/languages.md#language-fallbacks) correctly when retrieving pages in a specific language:
    - When retrieving pages with URL data from channels with language-specific domains via the [content item query](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api/content-item-query-api.md), use `SetUrlLanguageBehavior(UrlLanguageBehavior.UseRequestedLanguage)` or work with absolute URLs.
    - [Content retriever](https://docs.kentico.com/documentation/developers-and-admins/api/content-item-api/content-retriever-api.md) uses the appropriate `SetUrlLanguageBehavior` for language-specific domains by default. If you change it, work with absolute URLs.

- If links to the pages from the channel were previously used in the [rich text editor](https://docs.kentico.com/documentation/business-users/rich-text-editor.md), the links need to be updated.

- Former URL records are not converted. If any exist for the channel, the command lists their number in the output. Remove the associated records in the Former URL app to avoid clutter and non-functional URLs.

### Domain aliases and environment-specific domains

Domain aliases are alternative domain names that point to the same website. You can add any number of domain aliases to the main domain name. **Follow the configuration corresponding to the URL format of the channel.**

**Language prefix URL format**

Channel domain aliases can be configured programmatically using the `WebsiteChannelDomainOptions` options class and ASP.NET Core [configuration providers](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/).

For example, when configured via `appsettings.json`:

```json title="appsettings.json"
{
  "WebsiteChannelDomains": {
    "DomainOverrides": {
      "DancingGoatPages": {
        "Domains": [ "dancinggoat.com", "dancingllama.com" ]
      }
    }
  },
}
```

Where `DancingGoatPages` is the code name of the website channel to configure.

The system uses the **first** domain specified in the `Domains` array as the **main domain** (_dancinggoat.com_ in the example above). This configuration **takes priority** over the channel options set via the **General** tab in the Xperience user interface. The domain gets used, for example, when resolving relative links (in rich text content, email body). All additional domains are treated as **domain aliases** – they can be used to access the website, but are not reflected in URLs.

To apply the configuration from the appsettings, add the following code to `Program.cs`:

```csharp title="Program.cs"
using CMS.Websites;

var builder = WebApplication.CreateBuilder(args);

// Apply the configuration from appsettings.json
builder.Services.Configure<WebsiteChannelDomainOptions>(builder.Configuration.GetSection("WebsiteChannelDomains"));
```

For channels not configured via application settings, the values specified via the administration interface are used.

You can also make use of the [options pattern](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/options) to set different domains per [environment](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/environments) by introducing corresponding **appsettings.environment.json** files. The following example sets the primary domain to _localhost_ when the project is run under the _Development_ environment.

```json title="appsettings.Development.json"
{
  "WebsiteChannelDomains": {
    "DomainOverrides": {
      "DancingGoatPages": {
        "Domains": [ "localhost", "localdev.com" ]
      }
    }
  }
}
```

**Language-specific domains**

Assuming you already [configured](#configure-language-specific-domains) language-specific domains for your channel, you can add the aliases in the `WebsiteChannelDomainOptions` options class using the ASP.NET Core [configuration providers](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/).

The aliases need to be listed after the main domain name for a given language. The following example shows a configuration of a domain alias for English via `appsettings.json`:

```json title="appsettings.json"
{
  "WebsiteChannelDomains": {
    "LanguageDomains": {
      "<channel-code-name>": {
        "Domains": {
          "en": [ "dancinggoat.com", "dancinggoatalias.com" ],
          "fr": [ "fr.dancinggoat.com" ],
          "cs": [ "www.dancinggoat.cz"]
        }
      }
    }
  }
}
```

The visitors can use the alias to access the website, but the alias is not reflected in the URLs. Retrieving an absolute URL of a page language variant always returns the first domain specified for the language.

If you're using the appsettings file for configuration, the following code should already be present in your `Program.cs` file:

```csharp title="Program.cs"
using CMS.Websites;

var builder = WebApplication.CreateBuilder(args);

// Apply the configuration from appsettings.json
builder.Services.Configure<WebsiteChannelDomainOptions>(builder.Configuration.GetSection("WebsiteChannelDomains"));
```

You can also make use of the [options pattern](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/options) to set different domains per [environment](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/environments) by introducing corresponding **appsettings.environment.json** files. The following example specifies what domains to use for each language when the project is run under the _Staging_ environment.

```json title="appsettings.Staging.json"
{
  "WebsiteChannelDomains": {
    "LanguageDomains": {
      "<channel-code-name>": {
        "Domains": {
          "en": [ "staging.dancinggoat.com" ],
          "fr": [ "staging.dancinggoat.fr" ],
          "cs": [ "staging.dancinggoat.cz"]
        }
      }
    }
  }
}
```

### View configured domains in the admin UI

You can view the list of domains configured for a website channel in the current environment in the admin UI:

1. Open the **Channel management** application.
2. Select a channel.
3. Go to the **Domains** tab.

You can see a list of all configured domains, including [domain aliases](#domain-aliases-and-environment-specific-domains).

## Website channels in the SaaS environment

### Add website channels in Xperience Portal

For applications [deployed in the SaaS environment](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md), you need to add your channels in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md) after you create them in the [Xperience administration](#create-website-channels):

1. Open the **Channels and Domains → Channels** application in Xperience Portal.
2. Select **Add channel**.
3. Set the channel properties:
   - **Display name** – enter a name for the channel that will be displayed in Xperience Portal.
   - **Code name** – copy the exact code name of the [website channel](#create-website-channels) from the _Channel management_ application in the Xperience administration.
   - **Channel type** – _Website_
   - **Channel size** – select the same [channel size](#create-website-channels) as in the _Channel management_ application in the Xperience administration.
4. Select **Add channel**.

After you add a channel, the system automatically starts configuring channel domain settings for the deployed applications. This process may take up to several minutes. During this time you can continue configuring other channels and [domains](#add-custom-website-channel-domains).

Once you perform all required changes to channels and domains and after the configuration is completed by the system, select the **Apply changes** button in the information ribbon at the top of the interface and perform a final review of the changes you are about to apply. Applying these changes triggers a restart of the affected applications.

> **Tip:** You may need to manually refresh the current page for the **Apply changes** button to appear in the information ribbon.

When the domain and channel changes are applied, the content of the website channel becomes available under an automatically generated **Default domain** unless you [add suitable custom domains](#manage-channel-domains-in-xperience-portal) for the channel in production or staging environments.

> **Info:** For each new website channel, you can configure an uptime checker to monitor endpoint availability and receive alerts. See [Uptime monitoring](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#uptime-monitoring) for details.

### Manage channel domains in Xperience Portal

Website channels in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md) use the following types of domain names:

- **Default** – a default domain is generated for every website channel and environment. Default domains cannot be removed or altered.
- **Custom** – a custom domain added for the PROD or STG environment. This can be either an apex domain (_example.com_) or a subdomain (_www.example.com_, _sub.example.com_, ...).

  > **Info:** Each apex domain and subdomain is treated as an individual custom domain and need to be added separately.
  >
  > The number of available custom domains for a website channel depends on your [service plan](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md). By default, all service plans allow two custom domains per channel (one for the apex domain and one for the _www_ subdomain). Should you need additional custom domains for a single website channel, contact [Kentico sales](mailto:sales@kentico.com).
- **Main domain** – the primary domain set for the website channel, for example used in links to the site's pages. Each channel can only have one main domain, typically a custom domain name suitable for the production or staging environment.

### Add custom website channel domains

To set a custom domain for a website channel you need to add the domain in Xperience Portal and set the corresponding DNS records in the DNS registry of your domain provider. This scenario describes a simpler process to add new domain to non-public projects and may cause downtime to your application. If you want to add a new domain to a public project and minimize downtime, see [Add website channel domains with minimal downtime](#add-website-channel-domains-with-minimal-downtime).

1. Choose a domain name conforming to the following rules:
   - The website cannot run under a specific path, for example: _mysite.com/path_
   - The domain name cannot include a **port number** or **URL scheme**.
2. As a user with the _Tenant administrator_ or _DevOps Engineer_ [role](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal/reference-xperience-portal-user-roles.md), open the **Channels and Domains → Channels** application in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md).
3. Select the **Domains** () action for the chosen website channel.
4. Select **Add domain**.
5. Select **Standard (recommended)** as the domain creation method.
6. Choose the **Environment** (custom domains are only supported for production or staging environments) and select **Confirm**.
7. Enter the custom **Domain name** and select **Next**.
8. Xperience Portal displays the DNS records for your domain. Use the **Copy** () action to copy these records to your DNS registrar.
9. In your DNS registrar's control panel, add the copied DNS records. After you have successfully configured the DNS records with your registrar, return to Xperience Portal.
   - See [Configure DNS records for domain providers](https://docs.kentico.com/documentation/developers-and-admins/saas/configure-dns-records.md) for detailed instructions on configuring DNS records with popular providers.
10. Confirm that you have configured the DNS records by selecting **Confirm**. The system then validates your DNS configuration and creates the domain.
    - Note that DNS propagation can take up to 15 minutes, so the validation may require additional time to complete.
    - If the validation does not pass, an internal operation may have failed. You can select **Retry** to start another validation attempt.
    - If the validation fails due to DNS configuration issues, Xperience Portal displays the DNS records again. Verify the records are correctly configured in your DNS registrar, then select **Validate** to retry.
    - An auto-renewing SSL/TLS digital certificate is automatically created for the new domain when the validation finishes successfully.

![Website channel domains in Xperience Portal](https://docs.kentico.com/docsassets/documentation/website-channel-management/website_channel_domains_portal.png "Website channel domains in Xperience Portal")

After successful validation, you can select **Set as main domain** to set this domain as the primary domain for the channel.

After you add a channel, the system automatically starts configuring channel domain settings for the deployed applications. This process may take up to several minutes. During this time you can continue configuring other [channels](#add-website-channels-in-xperience-portal) and domains. You do not need to (and cannot) configure the channel's domain in the Xperience administration.

Once you perform all required changes to channels and domains and after the configuration is completed by the system, select the **Apply changes** button in the information ribbon at the top of the interface and perform a final review of the changes you are about to apply. Applying these changes triggers a restart of the affected applications.

> **Tip:** You may need to manually refresh the current page for the **Apply changes** button to appear in the information ribbon.

> **Info:** **License keys** for domain names of SaaS environment deployments are handled automatically, except for the _localhost_ domain. See [License keys for SaaS local development](https://docs.kentico.com/documentation/developers-and-admins/installation/licenses.md#licenses-saaslicensegenerator).

Your application is now available under the configured domain name.

You can see the **main domain** configured for each environment and website channel in the **Deployments** application in Xperience Portal.

![Viewing channel domains in the Deployments application](https://docs.kentico.com/docsassets/documentation/website-channel-management/deployment_channel_domains.png "Viewing channel domains in the Deployments application")

### Add website channel domains with minimal downtime

To set a custom domain for a website channel with minimal downtime to your application, you need to add the domain in Xperience Portal and set the corresponding DNS records in the DNS registry of your domain provider. This scenario describes a more complicated process to add a new domain to public projects while minimizing downtime. If you want to add a new domain to a non-public project and downtime is not a concern, see [Add custom website channel domains](#add-custom-website-channel-domains).

> **Info:** You validate DNS records twice in this scenario:
>
> 1. During **pre-validation** (initial DNS readiness check before activation).
>    - Xperience Portal verifies DNS records and creates a temporary SSL/TLS certificate.
> 2. Before the **final switch** (validation of the final DNS record used for activation).
>    - An auto-renewing SSL/TLS certificate is created after successful validation.

> **Note:** **Not supported for domains already on Cloudflare**
>
> This scenario pre-validates the domain with a TXT or HTTP token. Cloudflare does not support token pre-validation for a domain whose DNS zone is already hosted on Cloudflare, a setup Cloudflare calls _Orange-to-Orange_ (O2O). Pre-validation of such domains fails with a message stating that none of the A or AAAA records are owned by the account and that the pre-generated ownership verification token was not found.
>
> Add these domains using the [Standard method](#add-custom-website-channel-domains) instead and schedule the change for a maintenance window. For details on the limitation, see [Cloudflare's pre-validation documentation](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/pre-validation/).

#### Pre-validate the domain

1. Choose a domain name conforming to the following rules:
   - The website cannot run under a specific path, for example: _mysite.com/path_
   - The domain name cannot include a **port number** or **URL scheme**.
2. As a user with the _Tenant administrator_ or _DevOps Engineer_ [role](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal/reference-xperience-portal-user-roles.md), open the **Channels and Domains → Channels** application in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md).
3. Select the **Domains** () action for the chosen website channel.
4. Select **Add domain**.
5. Select **Pre-validation** as the domain creation method.
6. Choose the **Environment** (custom domains are only supported for production or staging environments).
7. Enter the custom **Domain name** and select **Next**.
8. Xperience Portal displays DNS records for your domain. Use the **Copy** () action to copy these records to your DNS registrar.
9. In your DNS registrar's control panel, add the copied DNS records. After you have configured the DNS records, return to Xperience Portal.
   - See [Configure DNS records for custom domains](https://docs.kentico.com/documentation/developers-and-admins/saas/configure-dns-records.md) for detailed instructions.
10. Select **Validate** to start pre-validation.
    - DNS propagation can take up to 15 minutes.
    - If validation fails for internal reasons, select **Retry** to start another validation attempt.
    - If validation fails due to DNS configuration issues, verify records and **Validate** again.
11. After pre-validation finishes, select **Apply changes** in the information ribbon.
    - You may need to manually refresh the current page for the **Apply changes** button to appear.
    - This action restarts affected applications and may briefly interrupt site availability. The domain remains active.
12. Continue immediately with the final switch, or return later.
    - The domain remains in pre-validation state until final validation and switch are completed.
    - If pre-validation DNS records expire or are removed, repeat step 10.

#### Validate final DNS and switch the domain

1. Copy the final DNS record shown by Xperience Portal to your DNS registrar and select **Validate**.
   - See [Configure DNS records for custom domains](https://docs.kentico.com/documentation/developers-and-admins/saas/configure-dns-records.md) for detailed instructions.
2. Wait for validation to finish.
   - DNS propagation can take up to 15 minutes.
   - If validation fails for internal reasons, select **Retry** to start another validation attempt.
   - If validation fails due to DNS configuration issues, verify DNS settings, wait a few minutes, and **Validate** again.
3. Finalize the switch with minimal delay between these actions:
   a. Use the **Home** () action to set the new custom domain as the main domain.
   b. Select **Apply changes** in the information ribbon.
   - This action restarts affected applications and may briefly interrupt site availability. The domain remains active.

Your application is now available under the configured domain name.

> **Info:** **License keys** for domain names of SaaS environment deployments are handled automatically, except for the _localhost_ domain. See [License keys for SaaS local development](https://docs.kentico.com/documentation/developers-and-admins/installation/licenses.md#licenses-saaslicensegenerator).

You can see the **main domain** configured for each environment and website channel in the **Deployments** application in Xperience Portal.

### Domain status

You can check the status of a channel's domains in the **Channels and Domains → Channels** application in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md). Select the **Domains** () action for a specific channel.

- **In progress** – The domain is being created.
- **Pre-validated** – The domain was successfully pre-validated.
- **Validating** – DNS records are being validated.
- **Pre-validating** – The domain is being pre-validated.
- **Apply changes pending** – The domain is ready but awaiting application of changes.
- **Pre-validation failed** – Pre-validation failed; reconfigure DNS records and retry.
- **Validation failed** – DNS records are configured incorrectly, or the configuration has not yet been propagated through the DNS servers.
- **Active** – The domain is active and working.

### Revalidate custom domains

Revalidating a custom domain is useful when DNS records were changed, DNS propagation took longer than expected, or domain status remains in a failed state.

To revalidate a custom domain in Xperience Portal:

1. Open the **Channels and Domains → Channels** application in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md).
2. Select the **Domains** () action for the related website channel.
3. Next to the domain whose validation failed, select **Continue** () to open the domain configuration step.
4. Select **Validate** again.
5. Wait for validation to complete and confirm that the domain status changes to **Active**.

If validation repeatedly fails even after verifying DNS records, contact [Kentico support](https://xperience.io/services/support).

### View DNS records of custom domains

You can view DNS records for any custom domain in the Xperience Portal:

1. Open the **Channels and Domains → Channels** application in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md) with a **Tenant administrator** or **DevOps Engineer** role.
2. Select the **Domains** () action for the related channel.
3. Select the **DNS records** () action.

   ![Action to view DNS records](https://docs.kentico.com/docsassets/documentation/website-channel-management/DNS_action.png "Action to view DNS records")

You can now see the DNS records for the domain. You can copy the values and use them, for example, with a new registrar.

## Configure DNS records

For detailed step-by-step guidance on configuring DNS records with your domain provider, see [Configure DNS records for custom domains](https://docs.kentico.com/documentation/developers-and-admins/saas/configure-dns-records.md). This page includes:

- Full step-by-step instructions for **Azure App Service** DNS configuration
- Instructions for **AWS Route 53**, **Cloudflare**, and other popular DNS providers
- Troubleshooting tips and best practices
- DNS propagation information and validation guidance