Organization administrators can provision customer hostnames when Xentree has enabled their organization's custom-domain entitlement.Set up in the dashboard#
Organization administrators can set up a custom domain without calling the API.1.
Open the Admin Panel / Dashboard.
2.
Under Organization, click Set up custom domain.
3.
Enter the subdomain you want to use as your URL, for example learn.yourcompany.com, then click Provision.
4.
Add the two DNS records shown in the popup at your DNS provider: a CNAME record and a TXT record.
5.
Wait until Verification and SSL change from Pending to Active. This can take a few minutes after DNS propagates.
Your organization must have the custom-domain entitlement, and the subdomain must follow the rules in step 1 below. The next section describes the same flow through the API.Step-by-step (API)#
Follow these steps to serve your organization on your own hostname, for example learn.yourcompany.com.Before you start#
You are an administrator of the organization and have a Bearer token.
Your organization is entitled to custom domains. This is included with the Team plan for organizations with 1,000 licenses, or 100 licenses on an annual subscription. Without it, both endpoints return 403.
You can edit DNS records for the domain you want to use.
1. Choose a hostname#
Use a subdomain of a domain you control, such as learn.yourcompany.com. The following are rejected with 422:A bare domain (yourcompany.com). A subdomain is required.
IP addresses and special-use names (.local, .internal, .test, .example, and similar). learn.customer.example in the examples below is a placeholder only.
xentree.ai and its subdomains.
Domains on shared hosting platforms (for example github.io, vercel.app, netlify.app, pages.dev).
URLs and ports are stripped, so https://Learn.YourCompany.com/ is stored as learn.yourcompany.com.2. Configure the domain#
Keep these from the response:cname_target: the DNS target for step 3.
cloudflare: provider-side details, used in step 4 if verification stays pending.
A new domain starts with verification_status and ssl_status at pending.Calling the endpoint again with the same domain does not create a second hostname. It refreshes the status instead. An organization can hold only one custom hostname. To replace it, contact Xentree support.Each administrator can configure a domain up to 10 times per hour. Beyond that the API returns 429 with a Retry-After header.3. Add the DNS records#
At your DNS provider, create two records:| Type | Name | Value |
|---|
| CNAME | learn (or the full hostname, depending on your provider) | the cname_target value from step 2 |
| TXT | the validation name provided by the provider | the validation value provided by the provider |
The TXT record details are in the cloudflare object of the response (the dashboard shows the same records in its popup).4. Check the status#
Each call refreshes pending status from the provider. Repeat it (for example every 30-60 seconds) until both fields are ready:| Field | Values | Ready when |
|---|
verification_status | pending, verified, failed | verified |
ssl_status | pending, active, failed | active |
If either stays pending for long, check that both the CNAME and the TXT record are in place and have propagated. The cloudflare object in the response shows the records the provider expects.If the provider is temporarily unreachable, this endpoint still returns 200 with the last stored state. Try again shortly.5. Confirm and use the domain#
Your domain serves your organization only when verification_status is verified and ssl_status is active. Then open https://learn.yourcompany.com to confirm. GET /api/organizations/{org_id} returns the same values in its custom_domain_* fields.The domain stops resolving if the organization becomes inactive or loses the custom-domain entitlement (for example, licenses drop below the threshold). It also stops if the provider later reports the hostname as blocked, failed or deleted.Troubleshooting#
| Response / symptom | Meaning and what to do |
|---|
403 | You are not an administrator of the organization, or the organization has no custom-domain entitlement. |
404 | Organization not found. |
409 | The domain is already assigned to another organization, or your organization already has a different custom hostname. Choose another hostname, or contact Xentree support to replace the existing one. |
422 | The hostname is not allowed. See step 1. |
429 | Too many configure attempts. Wait for the Retry-After period. |
502 | The provider failed to create the hostname. Retry later. If it persists, contact Xentree support. |
503 | The custom-domain service is not configured or unavailable. Contact Xentree support. |
verification_status or ssl_status is failed | Check that the CNAME points exactly to cname_target and that no conflicting record exists for the same name. If it persists, contact Xentree support. |
Stays pending | DNS may not have propagated yet, or the CNAME or TXT record is missing or wrong. See steps 3 and 4. |
Configure domain#
POST /api/admin/organizations/{org_id}/custom-domain{
"domain": "learn.customer.example"
}
Xentree superadmins can optionally include existing_cloudflare_hostname_id to adopt a hostname that was already created in Cloudflare instead of creating a new one. Other callers receive 403. The Cloudflare hostname must match domain, otherwise the API returns 422.Response contains cname_target, verification_status, ssl_status, and a cloudflare object with the provider-side hostname details. Point customer DNS CNAME at returned target, then poll status.Domain conflict returns 409; provider failure returns 502; unavailable provider configuration returns 503.Check status#
GET /api/admin/organizations/{org_id}/custom-domain/status returns current stored state and refreshes pending provider status when possible.Status fields#
The same values are mirrored on the organization object (GET /api/organizations/{org_id}):| Organization field | Status response field | Description |
|---|
custom_domain | custom_domain | Configured hostname |
custom_domain_cname_target | cname_target | CNAME target for your DNS |
custom_domain_verification_status | verification_status | Hostname ownership verification state |
custom_domain_ssl_status | ssl_status | SSL certificate issuance state |
cf_custom_hostname_id | cf_custom_hostname_id | Cloudflare custom hostname ID |
Both endpoints require Bearer auth, organization administrator role, and entitlement. Keep provider credentials server-side. Modified at 2026-10-29 11:19:39