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 using the Edge Platform Admin REST API and then validate it with your domain provider.

This walkthrough describes how to:

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

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 the Edge Platform API, then use information in the response to add records in your domain's DNS record.

To create a custom hostname:

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 default site ID attached to this hostname. 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`

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 default site ID attached to this hostname.

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:

RequestResponse

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:

RequestResponse

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

Copy and save the response. You'll need it to add a CNAME and TXT records to your domain's DNS record.

Add the CNAME and TXT records to your domain's DNS record

For hostname validation and domain control validation (DCV), you need to add TXT records to your domain's DNS record. You also need to add a CNAME record to associate your custom hostname with the Sitecore proxy.

The way that you add a DNS record varies, depending on your domain host.

In general, to add DNS records:

Sign in to your domain registrar with the account you used to buy your domain.
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.
For hostname 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.
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.
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.

To check the status of your custom hostname:

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

RequestResponse

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

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.

Do you have some feedback for us?

If you have suggestions for improving this article,