--- title: "Set up a custom hostname" slug: "set-up-a-custom-hostname" abstract: "How to set up a custom hostname." --- # Set up a custom hostname This walkthrough describes how to set up a custom hostname. A custom hostname enables access to Sitecore APIs using a subdomain of your organization's domain. For example `{YOUR_CUSTOM_HOSTNAME}.example.com`. You can add a custom hostname to access Sitecore APIs using your own domain. To set up a custom hostname, you first need to create it from the Sitecore Cloud Portal or using the [Edge Platform Admin REST API](https://api-docs.sitecore.com/portal/edge-platform-admin-rest-api) and then validate it with your domain provider. This walkthrough describes how to: :::walkthrough 1. [Create a custom hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames/set-up-a-custom-hostname.html#create-a-custom-hostname) 2. [Validate hostname ownership](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames/set-up-a-custom-hostname.html#validate-hostname-ownership) 3. [Check the status of your custom hostname](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames/set-up-a-custom-hostname.html#check-the-status-of-your-custom-hostname) ::: > [!note] > **Before you begin** > - You must be an *Organization Admin* or *Organization Owner* in your Sitecore Cloud Portal organization. > > - You must have a domain name and the ability to create a TXT record with your domain host. ## Create a custom hostname > [!note] > Currently, a custom hostname must be a subdomain such as `.example.com`. Wildcards and apex domains are not supported. You need to create a custom hostname using either the Sitecore Cloud Portal or the Edge Platform API, then use information in the response to add records in your domain's DNS record. The maximum number of hostnames you can create is determined by your contract. To increase this limit, please contact your Sitecore representative. To create a custom hostname: ::::tabs :::tab{title="Browser"} ### Sitecore Cloud Portal 1. Open the [Custom hostnames page](https://portal.sitecorecloud.io/admin/custom-hostnames), then click **Create custom hostname**. 2. In the **Create custom hostname** dialog, in the **Hostname** field, enter the custom hostname to be created. Wildcards and apex domains are not supported. 3. In the **Default Context ID** field, enter the default [context ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/en/context-id-environment-variables.html) associated with the custom hostname. If you don't specify a value for default context ID now, you'll need to provide a context ID in the query parameter or header every time you make a request to the hostname. > [!note] > Custom hostnames can only be used with the live context ID and for media items published to Experience Edge. 4. In the **Default site ID** field, enter the name of the site you want to attach to this hostname. The site ID is the value of the `SITECORE_SITE_NAME` variable in the Developer settings tab in the Deploy app. If you don't specify a value for default site ID now, you'll need to provide a site ID in the query parameter or body every time you make a request to the hostname. 5. Click **Create**. The hostname will be created and the **Hostname records** dialog will pop up. ::: :::tab{title="Server"} ### Edge Platform API 1. Log in to your [Sitecore Cloud Portal](https://portal.sitecorecloud.io/) organization, then in the top-right corner of the menu bar, click your profile ![profile.PNG](https://doc.sitecore.com/api/markdown-image/portal/en/developers/sitecore-cloud-portal/images/profile.PNG) > **API tokens**, then copy the **Bearer token**. 2. Make a POST request to `https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames` using the [create a custom hostname API endpoint](https://api-docs.sitecore.com/portal/edge-platform-admin-rest-api/organizations/post_em). | Name | Description | Example | | --- | --- | --- | | `hostname` | The custom hostname to be created. Wildcards and apex domains are not supported. | `example.site.com` | | `defaultContextId` | The default [context ID](https://doc.sitecore.com/xmc/en/developers/xm-cloud/en/context-id-environment-variables.html) associated with the custom hostname.

If you don't specify a value for default context ID now, you'll need to provide a context ID in the query parameter or header every time you make a request to the hostname. | 4N1c0nt3xtjDksn997CRp9T | | `defaultSiteId` | The name of the site you want to attach to this hostname. The site ID is the value of the `SITECORE_SITE_NAME` variable in the [Developer settings tab in the SitecoreAI Deploy app](https://doc.sitecore.com/xmc/en/developers/xm-cloud/get-the-environment-variables-for-a-site.html).

If you don't specify a value for default site ID now, you'll need to provide a site ID in the query parameter or body every time you make a request to the hostname. | `exampleSitecoreSite` | Sample request: ```curl curl --location 'https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "hostname": "example.site.com", "defaultSiteId": "exampleSitecoreSite", "defaultContextId": "4N1NYjlsn100VAsCNrRp9T" }' ``` Sample response: ```json { "id": "9f848e0f-e12a-4e93-9989-0ff368033bb", "defaultContextId": "4N1NYjlsn100VAsCNrRp9T", "defaultSiteId": "exampleSitecoreSite", "hostname": "example.site.com", "ssl": { "method": "txt", "status": "pending_validation", "validation_errors": [], "validation_records": [ { "txt_name": "_acme-challenge.example.site.com", "txt_value": "2_hWDRQIToMYxecCennD1WXLdhiou1cHV0meL0jUI" } ] }, "ownership_verification": { "name": "_cf-custom-hostname.example.site.com", "type": "txt", "value": "45550fdb-1123-4b87-9ec8-htr1e2e3a39" }, "created_at": "2069-09-03T14:`26:51`.518323Z", "status": "pending" } ``` 3. Copy and save the response. You'll need it to add a CNAME and TXT records to your domain's DNS record. ::: :::: ## Validate hostname ownership To configure a custom hostname, add the DNS records provided in the **Hostname records** dialog (if using the Sitecore Cloud Portal) or the HTTP response (if using the Edge Platform API). Depending on the hostname validation method used, these records can include: - A *TXT Hostname Validation* record to verify ownership or administrative control of the hostname. - A *TXT SSL Validation* record for Domain Control Validation (DCV), enabling SSL certificate issuance and management. - A *CNAME* record to associate your custom hostname with the Sitecore proxy. When configuring a custom hostname, there are two methods available for hostname ownership validation: - Automatic validation without TXT Hostname Validation - Ownership is validated automatically after the CNAME record is added. - Simpler DNS configuration, but switching the CNAME before validation completes can cause temporary downtime if the hostname is already serving live traffic. - Pre-validation with TXT Hostname Validation - Ownership is verified by adding a TXT Hostname Validation record before the CNAME record is switched. - Validation and certificate provisioning can be completed before traffic is routed, helping minimize or avoid downtime when onboarding an existing hostname. However, this approach requires additional DNS configuration steps, including adding a TXT Hostname Validation record to your DNS zone. The way that you add a DNS record varies, depending on your domain host. In general, to add DNS records: ::::tabs :::tab{title="Browser"} ### Sitecore Cloud Portal 1. Sign in to your domain registrar with the account you used to buy your domain. 2. Go to the section where you can update your domain's TXT and CNAME records. This is typically called: DNS settings, DNS management, or advanced settings. 3. If using pre-validation, add a TXT record using the information in the **TXT Hostname validation** section of the **Hostname records** dialog. If you closed the dialog, in the **Custom hostnames** page, click **Add records**. 4. For SSL validation, add a TXT record using the information in the **TXT SSL validation** section. 5. Add a CNAME record using the information in the **CNAME** section. For some examples, see [Google's custom instructions for many popular domain registrars](https://support.google.com/a/topic/1409901). ::: :::tab{title="Server"} ### Edge Platform API 1. Sign in to your domain registrar with the account you used to buy your domain. 2. Go to the section where you can update your domain's TXT and CNAME records. This is typically called: DNS settings, DNS management, or advanced settings. 3. If using pre-validation, add a TXT record with the following information from the response you generated earlier: - Name - the value of `ownership_verification.name`, not including the apex domain. For example, if the value is `_acme-challenge.example.site.com`, use `_acme-challenge.example` as the value. - Value - the value of `ownership_verification.value`. 4. For DCV, add a TXT record with the following: - Name - the value of `ssl.validation_records.txt_name`, not including the apex domain. - Value - the value of `ssl.validation_records.txt_value`. 5. Add a CNAME record with the following: - Name - the value of `hostname`. - Target - `sitecoreproxy.io` For some examples, see [Google's custom instructions for many popular domain registrars](https://support.google.com/a/topic/1409901). ::: :::: ## Check the status of your custom hostname After adding the required DNS records to your domain registrar, your hostname will typically be active within 10 minutes. > [!note] > **Hostname validation status and lifecycle** > > After you create a custom hostname and add the required DNS records, the hostname enters a validation period. A hostname starts in Pending validation. If it fails validation long enough, it can move to *Moved* status. A hostname may also enter *Moved* if the DNS record no longer points to the expected fallback origin. > > If it stays in *Moved* for more than 7 days, it will transition to *Deleted* automatically. *Deleted* means the hostname is inactive and scheduled for cleanup. > > A user can restart validation by sending a refresh or PATCH request. To check the status of your custom hostname: ::::tabs :::tab{title="Browser"} ### Sitecore Cloud Portal In the **Custom hostname** page, see the **Hostname status** of your custom hostname. When the status is **ACTIVE**, it is ready to use. ::: :::tab{title="Server"} ### Edge Platform API 1. Make a GET request to `https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/` ```curl curl --location 'https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.site.com' \ --header 'Authorization: Bearer ' ``` 2. In the response, check if the value of the `status` is `active`. This means your hostname is ready to use. ::: :::: After you've added your custom hostname, you can use it to [route traffic to specific Sitecore services](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/custom-hostnames/resolving-a-custom-hostname-during-a-request.html "Resolving a custom hostname during a request").