Create a custom hostname

Sitecore Edge Platform Admin API (1.0)

Use the Edge Platform Admin API to create, retrieve, update, and delete custom hostnames in your organization.

This REST API lets you interact with:

The custom hostname object. Use a custom hostname to serve content or direct traffic to specific web services or applications under your organization's domain.

After creating a custom hostname, you must:

Register the hostname. Add the CNAME and TXT records to verify domain ownership.
Check the status. Ensure that it is active before using the hostname.

Note the following:

You must have an Organization Admin or Organization Owner role in Sitecore Cloud Portal.
To use this REST API, you must authenticate your API requests.
All API requests are made in your production environment.

For more information, see the official Sitecore Portal developer documentation.

Authentication

The Edge Platform Admin API uses bearer authentication.

Bearer authentication involves security tokens called bearer tokens, which are generated in response to a login request.

To get the bearer token:

Log in to Sitecore Cloud Portal.
In the top-right corner of the menu bar, click your profile > API tokens.
Click Copy to clipboard.

You can now start making REST API requests. You must include this token in the authorization header of every request you make.

Download OpenAPI description

index.json

index.yaml

Overview

License Apache 2.0

Servers

Production server

https://edge-platform-admin-api.sitecorecloud.io/

Organizations

The Organizations API lets you create and manage custom hostnames in your organization.

Operations

Create a custom hostname

Request

Creates a custom hostname in your organization by specifying a hostname, a defaultSiteId, and a defaultContextId. Wildcards and apex domains are not currently supported for naming hostnames.

The number of custom hostnames you can create is limited by your organization's XM Cloud account entitlement. If this limit is exceeded, an error message is returned, and the custom hostname won't be created.

After it is created, the custom hostname details are stored and used to resolve and route traffic for incoming requests.

Bodyapplication/json

hostnamestringrequired

The unique name assigned to a custom hostname.

Example: "sitecore-api-preview.example.com"

defaultSiteIdstring

The default site ID associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is resolved correctly.

Example: "playsummit"

defaultContextIdstring

The default context ID associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is resolved correctly.

Example: "3BTl4aU7w12A5M76m9p8IA"

curl -i -X POST \
  https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "hostname": "sitecore-api-preview.example.com",
    "defaultSiteId": "playsummit",
    "defaultContextId": "3BTl4aU7w12A5M76m9p8IA"
  }'

Responses

Accepted

Bodyapplication/json

idstringrequired

The custom hostname's unique identifier generated during creation.

Example: "08de73f4-6f01-49b2-9ca6-d7fab7de966d"

hostnamestringrequired

The unique name assigned to a custom hostname.

Example: "sitecore-api-preview.example.com"

sslobjectrequired

The custom hostname's SSL properties, such as the domain control validation method, validation status, and related DNS records.

ssl.expires_onstringrequired

The SSL certificate's expiration date and time.

Example: "2021-02-06T18:11:23.531995Z"

ssl.methodstringrequired

The validation method used to verify the SSL certificate.

Example values: "txt", "html"

Example: "txt"

ssl.statusstringrequired

The current status of the SSL certificate.

Example values: "pending_validation", "active".

Example: "active"

ssl.validation_recordsArray of objectsrequired

The TXT records used for domain control validation (DCV).

ssl.validation_records[].txt_namestring

The name of the TXT record used for DCV.

When adding this name to your DNS provider for DCV, you must exclude the domain name. For example, the TXT record name must be _acme_challenge.

Example: "_acme_challenge.sitecore-api-preview.example.com"

ssl.validation_records[].txt_valuestring

The value of the TXT record used for DCV.

Example: "9kGetV9XSlo0VXSrU1sYHeEwc36xmkFY-a0J-4CGq8c"

ssl.validation_errorsArray of objectsrequired

Errors encountered during domain control validation.

ssl.validation_errors[].messagestring

The error description.

Example: "SERVFAIL looking up CAA for app.example.com"

defaultSiteIdstring

The default site ID associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is resolved correctly.

Example: "playsummit"

defaultContextIdstring

The default context ID associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is resolved correctly.

Example: "3BTl4aU7w12A5M76m9p8IA"

ownership_verificationobject

The DNS records required to verify ownership of the custom hostname.

created_atstring

The date and time the custom hostname was created.

Example: "2021-02-06T18:11:23.531995Z"

statusstring

The current status of the custom hostname.

Example values: "pending", "active".

Example: "active"

verification_errorsArray of strings

A list of errors that occurred while verifying the ownership of the custom hostname.

Example: ["SERVFAIL looking up CAA for app.example.com"]

Response

application/json

{
  "id": "08de73f4-6f01-49b2-9ca6-d7fab7de966d",
  "hostname": "sitecore-api-preview.example.com",
  "defaultSiteId": "playsummit",
  "defaultContextId": "3BTl4aU7w12A5M76m9p8IA",
  "ssl": {
    "expires_on": "2021-02-06T18:11:23.531995Z",
    "method": "txt",
    "status": "active",
    "validation_records": [ … ],
    "validation_errors": [ … ]
  },
  "ownership_verification": {
    "name": "_cf_custom-hostname.sitecore-api-preview.example.com",
    "type": "txt",
    "value": "e5e19fb0-0666-449d-a5ae-414f485dc63b"
  },
  "created_at": "2021-02-06T18:11:23.531995Z",
  "status": "active",
  "verification_errors": [
    "SERVFAIL looking up CAA for app.example.com"
  ]
}

List custom hostnames

Request

Retrieves the list of all custom hostnames in your organization. This lets you check if a certain hostname already exists.

If the hostname exists and you need to retrieve, update, or delete it, you can use the appropriate endpoint to perform the desired action.

curl -i -X GET \
  https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful operation

Bodyapplication/json

idstringrequired

The custom hostname's unique identifier generated during creation.

Example: "08de73f4-6f01-49b2-9ca6-d7fab7de966d"

hostnamestringrequired

The unique name assigned to a custom hostname.

Example: "sitecore-api-preview.example.com"

sslobjectrequired

The custom hostname's SSL properties, such as the domain control validation method, validation status, and related DNS records.

ssl.expires_onstringrequired

The SSL certificate's expiration date and time.

Example: "2021-02-06T18:11:23.531995Z"

ssl.methodstringrequired

The validation method used to verify the SSL certificate.

Example values: "txt", "html"

Example: "txt"

ssl.statusstringrequired

The current status of the SSL certificate.

Example values: "pending_validation", "active".

Example: "active"

ssl.validation_recordsArray of objectsrequired

The TXT records used for domain control validation (DCV).

ssl.validation_records[].txt_namestring

The name of the TXT record used for DCV.

When adding this name to your DNS provider for DCV, you must exclude the domain name. For example, the TXT record name must be _acme_challenge.

Example: "_acme_challenge.sitecore-api-preview.example.com"

ssl.validation_records[].txt_valuestring

The value of the TXT record used for DCV.

Example: "9kGetV9XSlo0VXSrU1sYHeEwc36xmkFY-a0J-4CGq8c"

ssl.validation_errorsArray of objectsrequired

Errors encountered during domain control validation.

ssl.validation_errors[].messagestring

The error description.

Example: "SERVFAIL looking up CAA for app.example.com"

defaultSiteIdstring

The default site ID associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is resolved correctly.

Example: "playsummit"

defaultContextIdstring

The default context ID associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is resolved correctly.

Example: "3BTl4aU7w12A5M76m9p8IA"

ownership_verificationobject

The DNS records required to verify ownership of the custom hostname.

created_atstring

The date and time the custom hostname was created.

Example: "2021-02-06T18:11:23.531995Z"

statusstring

The current status of the custom hostname.

Example values: "pending", "active".

Example: "active"

verification_errorsArray of strings

A list of errors that occurred while verifying the ownership of the custom hostname.

Example: ["SERVFAIL looking up CAA for app.example.com"]

Response

application/json

{
  "id": "08de73f4-6f01-49b2-9ca6-d7fab7de966d",
  "hostname": "sitecore-api-preview.example.com",
  "defaultSiteId": "playsummit",
  "defaultContextId": "3BTl4aU7w12A5M76m9p8IA",
  "ssl": {
    "expires_on": "2021-02-06T18:11:23.531995Z",
    "method": "txt",
    "status": "active",
    "validation_records": [ … ],
    "validation_errors": [ … ]
  },
  "ownership_verification": {
    "name": "_cf_custom-hostname.sitecore-api-preview.example.com",
    "type": "txt",
    "value": "e5e19fb0-0666-449d-a5ae-414f485dc63b"
  },
  "created_at": "2021-02-06T18:11:23.531995Z",
  "status": "active",
  "verification_errors": [
    "SERVFAIL looking up CAA for app.example.com"
  ]
}

Retrieve a custom hostname

Request

Retrieves a specific custom hostname in your organization, including details such as defaultSiteId, defaultContextId, and SSL certificate information.

If you don't know the exact hostname, first retrieve all custom hostnames within your organization using the List custom hostnames endpoint.

Path

hostnamestringrequired

The specific custom hostname you want to interact with.

Example: sitecore-api-preview.example.com

curl -i -X GET \
  'https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/{hostname}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful operation

Bodyapplication/json

idstringrequired

The custom hostname's unique identifier generated during creation.

Example: "08de73f4-6f01-49b2-9ca6-d7fab7de966d"

hostnamestringrequired

The unique name assigned to a custom hostname.

Example: "sitecore-api-preview.example.com"

sslobjectrequired

The custom hostname's SSL properties, such as the domain control validation method, validation status, and related DNS records.

ssl.expires_onstringrequired

The SSL certificate's expiration date and time.

Example: "2021-02-06T18:11:23.531995Z"

ssl.methodstringrequired

The validation method used to verify the SSL certificate.

Example values: "txt", "html"

Example: "txt"

ssl.statusstringrequired

The current status of the SSL certificate.

Example values: "pending_validation", "active".

Example: "active"

ssl.validation_recordsArray of objectsrequired

The TXT records used for domain control validation (DCV).

ssl.validation_records[].txt_namestring

The name of the TXT record used for DCV.

When adding this name to your DNS provider for DCV, you must exclude the domain name. For example, the TXT record name must be _acme_challenge.

Example: "_acme_challenge.sitecore-api-preview.example.com"

ssl.validation_records[].txt_valuestring

The value of the TXT record used for DCV.

Example: "9kGetV9XSlo0VXSrU1sYHeEwc36xmkFY-a0J-4CGq8c"

ssl.validation_errorsArray of objectsrequired

Errors encountered during domain control validation.

ssl.validation_errors[].messagestring

The error description.

Example: "SERVFAIL looking up CAA for app.example.com"

defaultSiteIdstring

The default site ID associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is resolved correctly.

Example: "playsummit"

defaultContextIdstring

The default context ID associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is resolved correctly.

Example: "3BTl4aU7w12A5M76m9p8IA"

ownership_verificationobject

The DNS records required to verify ownership of the custom hostname.

created_atstring

The date and time the custom hostname was created.

Example: "2021-02-06T18:11:23.531995Z"

statusstring

The current status of the custom hostname.

Example values: "pending", "active".

Example: "active"

verification_errorsArray of strings

A list of errors that occurred while verifying the ownership of the custom hostname.

Example: ["SERVFAIL looking up CAA for app.example.com"]

Response

application/json

{
  "id": "08de73f4-6f01-49b2-9ca6-d7fab7de966d",
  "hostname": "sitecore-api-preview.example.com",
  "defaultSiteId": "playsummit",
  "defaultContextId": "3BTl4aU7w12A5M76m9p8IA",
  "ssl": {
    "expires_on": "2021-02-06T18:11:23.531995Z",
    "method": "txt",
    "status": "active",
    "validation_records": [ … ],
    "validation_errors": [ … ]
  },
  "ownership_verification": {
    "name": "_cf_custom-hostname.sitecore-api-preview.example.com",
    "type": "txt",
    "value": "e5e19fb0-0666-449d-a5ae-414f485dc63b"
  },
  "created_at": "2021-02-06T18:11:23.531995Z",
  "status": "active",
  "verification_errors": [
    "SERVFAIL looking up CAA for app.example.com"
  ]
}

Update a custom hostname

Request

Partially updates a custom hostname by replacing the defaultSiteId, defaultContextId, or both, as needed.

The hostname itself cannot be updated after the custom hostname has been created and registered. As a workaround, you must delete the existing custom hostname and create a new one to change the hostname.

Path

hostnamestringrequired

The specific custom hostname you want to interact with.

Example: sitecore-api-preview.example.com

Bodyapplication/json

defaultSiteIdstring

The default site ID associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is resolved correctly.

Example: "playsummit"

defaultContextIdstring

The default context ID associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is resolved correctly.

Example: "3BTl4aU7w12A5M76m9p8IA"

curl -i -X PATCH \
  'https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/{hostname}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "defaultSiteId": "playsummit",
    "defaultContextId": "3BTl4aU7w12A5M76m9p8IA"
  }'

Responses

Accepted

Bodyapplication/json

defaultSiteIdstring

The default site ID associated with the custom hostname.

If you don't specify a value for defaultSiteId, you'll need to manually include it in the query parameter or body with each request to the custom hostname to ensure it is resolved correctly.

Example: "playsummit"

defaultContextIdstring

The default context ID associated with the custom hostname.

If you don't specify a value for defaultContextId, you'll need to manually include it in the query parameter or header with each request to the custom hostname to ensure it is resolved correctly.

Example: "3BTl4aU7w12A5M76m9p8IA"

Response

application/json

{
  "defaultSiteId": "playsummit",
  "defaultContextId": "3BTl4aU7w12A5M76m9p8IA"
}

Delete a custom hostname

Request

Deletes a custom hostname and all its associated details. This is an irreversible operation.

Path

hostnamestringrequired

The specific custom hostname you want to interact with.

Example: sitecore-api-preview.example.com

curl -i -X DELETE \
  'https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/{hostname}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

No Content

Response

application/json

{
  "status": 400,
  "title": "BAD REQUEST",
  "detail": "URL format is invalid",
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "instance": "https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames/example.com"
}

Sitecore Edge Platform Admin API (1.0)

Authentication

Organizations

Create a custom hostname

Request

Responses

Was this helpful?

List custom hostnames

Request

Responses

Was this helpful?

Retrieve a custom hostname

Request

Responses

Was this helpful?

Update a custom hostname

Request

Responses

Was this helpful?

Delete a custom hostname

Request

Responses

Was this helpful?