A valid request URL is required to generate request examples{
"connected": true,
"custom_domain_available": true,
"host": "accounts.example.com",
"status": "pending",
"status_detail": "<string>",
"verification": [
{
"type": "CNAME",
"domain": "<string>",
"value": "<string>",
"reason": "<string>"
}
],
"last_checked_at": "2023-11-07T05:31:56Z",
"verified_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Connect a custom portal domain
Requires org:update, and a plan that includes a custom domain — this is the only act on this surface that a plan can refuse. Reading, re-checking and disconnecting are free on every plan.
The host is claimed globally: two organizations cannot both own one address, and the second one to ask gets 409. Sending a different host for an environment that already has one replaces it, and the status resets — a new address has never been checked, and inheriting verified from the previous one would claim a domain works because a different one did. Replacing releases the old address first: if that fails the call answers 503 and nothing changes, because a name still routed to us with no record of who owns it is a name anybody could claim next.
The answer carries the DNS records to create. Nothing is verified yet; call POST .../verify once the records are in place.
A valid request URL is required to generate request examples{
"connected": true,
"custom_domain_available": true,
"host": "accounts.example.com",
"status": "pending",
"status_detail": "<string>",
"verification": [
{
"type": "CNAME",
"domain": "<string>",
"value": "<string>",
"reason": "<string>"
}
],
"last_checked_at": "2023-11-07T05:31:56Z",
"verified_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Path Parameters
The environment's id.
Body
The exact address, without a scheme, a port or a wildcard.
"accounts.example.com"
Response
Claimed, pending DNS.
The address your customers reach the hosted portal at.
connected is false for an environment that has none, which is a state a screen renders rather than a 404 — and custom_domain_available still answers, because a screen has to know whether the capability exists on the server before it offers the form.
Every status that is not verified names a different repair.
Whether this environment has claimed a host. The fields below it are present only when true.
Whether the server can register a custom domain at all. False means connecting answers 501, whatever else is reported here.
"accounts.example.com"
pending: nothing answers for this host yet — add the records in verification. misconfigured: something answers and it is not us — remove or replace it. verified: nothing to do. Only an explicit yes from the edge ever reaches verified.
pending, misconfigured, verified Why it is not verified, in the edge's own words. Empty on a verified domain. Never parse it.
The DNS records to create. Stored as the edge described them rather than recomputed, because an apex takes an A record and a subdomain a CNAME — which one is not ours to decide.
Show child attributes
Show child attributes
When we last asked, whatever the answer — it moves even when the edge could not be reached, which is what separates "checked a minute ago" from "nobody has looked since Tuesday".
When it first answered yes. Kept through a later misconfigured: a domain that worked and stopped is a different problem from one that never worked.