1. Custom hostnames

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 and then validate it with your domain provider.

This walkthrough describes how to:

  1. Create a custom hostname

  2. Validate hostname ownership

  3. Check the status of your custom hostname

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 <your-custom-hostname>.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:

Sitecore Cloud Portal

  1. Open the Custom hostnames page, 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 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.

Edge Platform API

  1. Log in to your Sitecore Cloud Portal organization, then in the top-right corner of the menu bar, click your profile > 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.

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

    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 --location 'https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
--data '{
  "hostname": "example.site.com",
  "defaultSiteId": "exampleSitecoreSite",
  "defaultContextId": "4N1NYjlsn100VAsCNrRp9T"
}'

    Sample response:

    {
    "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:

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.

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.

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:

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.

Edge Platform API

  1. Make a GET request to https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/<your-custom-hostname>

    curl --location 'https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.site.com' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

  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.

If you have suggestions for improving this article, let us know!