Sitecore API catalog/Edge Platform Admin API/Organizations

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.

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

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.

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