Create a domain connection (idempotent per app + domain)

Create a domain connection (idempotent per app + domain): CustomDomain™ API reference in the connections group. Covers parameters, request body and responses.

Starts connecting domain under the calling application and returns the connection plus its authoritative desired record set. Idempotent: if the app already has a non-failed connection for the domain, that existing connection is replayed with 200.

A widget token is never handed another end user's connection. When the application already has a connection for the domain (live, or failed and about to be resumed) that names another end user than the token's end_user_ref, or names one while the token names none, the call answers 403 token_wrong_end_user and shows nothing of it: no id, no field, and a failed connection is not resumed. Mint the token with the end user's end_user_ref. The replay is unchanged for the end user's own token, for a connection that names no end user (an API key made it), for an API key, an app-scoped token and a delegated agent token.

A domain another application already serves live is refused with 409 domain_already_connected before anything is written: move it by disconnecting it there first. When the ownership TXT flow is on the claim is accepted instead, and the ownership challenge decides it.

Callable from the widget (a widget JWT) or straight from your server with an API key, in which case the connection is created on the key's application, or on application_id when that names another application of the same tenant.

A delegated agent token needs domains:connect and creates the connection on its own application. Its answer, a replayed connection included, carries no end_user_ref, the platform's id for its end user. It cannot set the end user's e-mail address: a body with a non-empty end_user_email is refused with 403, and the platform's API key sets it.

A name under a zone CustomDomain™ already hosts joins it without a new move, and the 201 shows it already live when its records resolve. The registrable domain's zone must be active (delegated to us) and hosted for this application. A widget token joins only a zone that is its own by the rule every managed DNS call of a widget token follows: the new connection is the token's, and so is every connection already linked to the zone (a connection that names an end user is the token's when its end_user_ref is the token's; one that names none is the token's only for a name the token is bound to). The connection that started the zone does not decide it, so a zone that an API key, the console or another end user also linked a name to is not the token's. The application must still offer DNS hosting on CustomDomain™'s own DNS. An API key or an app scoped token joins its own application's zone. A delegated agent token, a widget token that does not own the zone, and every other zone change nothing: the name proves control by DNS as always, and no record is written into a zone that is not the caller's. The records written are in the audit log as dns.hosted_zone_joined.

A workspace with no subscription yet connects its first ten domains, or the number an operator set, without one (first_domain_free and free_domains on the billing reads): a retry of the last of them is still replayed with 200, and the next domain is refused with 402 billing_required until the workspace starts its trial. A domain that is still waiting for its records can be removed with DELETE /connections/{id}, which frees its place at once.

Authorization

AuthorizationBearer <token>

Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The body is decoded with unknown fields REJECTED, so the properties below are exactly the accepted set: any other key is a 400. Everything besides domain is optional.

domain*string

application_url?string

Origin the edge reverse-proxies this connection's traffic to (Power). Validated on the way in: it must be an absolute http(s) URL with a public host; private, loopback and cloud-metadata targets are rejected with a 400. Power is part of the Growth plan and up: on a plan without it the create is refused with 402 plan_upgrade_required and nothing is stored. Omit to leave the edge on its own router.

Formaturi

www_redirect?boolean

Serve an apex↔www redirect for this connection.

Defaultfalse

override_spf?boolean

Replace an existing SPF record instead of merging into it. Honoured only for providers whose connection check reports spf_override_support as true; for every other provider the existing record is merged, as when this is false.

Defaultfalse

validate_dmarc?boolean

Accepted, stored with the connection and echoed back. It is not acted on yet: DMARC is not checked during verification today.

Defaultfalse

validate_caa?boolean

Adds the two apex CAA records that authorize Let's Encrypt (issue and issuewild) to the connection's desired record set, skipping any already present. No separate CAA check is run against the domain's existing records. Edge routing only: a domain routed to your own infrastructure (a connect target) gets its certificate there, so no CAA records are added for it.

Defaultfalse

monitor?boolean

Enrol the domain in drift monitoring: once the connection goes live the control plane registers a drift watch and the hourly sweeper re-checks the connection's DNS records, emitting domain.record_missing / domain.record_restored when they change. Unlike the four flags above this one DEFAULTS TO TRUE: omitting it enrols the domain. That is deliberate back-compat: the watch used to be registered unconditionally, so every connection created before this flag was honoured is monitored, and every existing integrator omits the field. Send false to opt a connection out; the value is echoed on the connection and is the only thing that decides whether the watch is registered. The plan's Monitor entitlement is not enforced today: monitoring is registered for every connection that has this on, regardless of plan.

Defaulttrue

batch_id?string

Caller-supplied id correlating every domain connected in one multi-domain session. Stamped on each connection and echoed back; empty for a standalone connect. Set once at create.

end_user_ref?string

The integrator's OWN identifier for the end user this connect is attributed to, so the console can render "Connected by …" and search by customer. Empty ⇒ a console/direct connect. Set once at create and never mutated. It binds a widget token and saved access to the connection, so it is an id and not a name: to name the client a domain is for, send client_label.

client_label?string

The name of the client or customer this domain is for, shown in the console beside the domain and used by its client filter. Trimmed to one line, at most 200 characters, with characters that draw nothing dropped; a name with nothing left stores no name. Unlike end_user_ref nothing is bound to it, and PATCH /connections/{id} changes it later. Only an API key or an app-scoped token may send it: an end user's widget token or a delegated agent token that does is refused with 403. A replay of a domain that already exists keeps the name it has.

Lengthlength <= 200

end_user_email?string

Optional. The email address of the end user this domain is connected for. After a Move they get one email with the new DNS records, sent on your behalf and naming your application (at most 3 per connection in 30 days). It wins over an address given when the token was minted, is stored only on the connection, and is shown back only in this call's response and on GET /connections/{id} with an API key. Only an API key replaces an address the connection already has: a widget token's create keeps the stored one (as PUT /connections/{id}/end-user-email answers it with 409), and a delegated agent token that sends one is refused with 403, since the reconnect email goes to this address and carries a link that signs in as the end user. For the same reason a widget token bound to another end user than the connection's (end_user_ref) stores no address, neither this one nor one given when the token was minted, and is not asked for one.

Formatemail

Lengthlength <= 254

application_id?string

API key callers only: create the connection on this application of the key's tenant. A widget or agent token may only name its own application (anything else is a 403).

Response Body

`application/json`

curl -X POST "https://example.com/connections" \  -H "Content-Type: application/json" \  -d '{    "domain": "string"  }'

{  "id": "string",  "application_id": "string",  "domain": "string",  "host": "string",  "provider_id": "string",  "setup_type": "automatic",  "status": "pending",  "managed": true,  "created_at": "2019-08-24T14:15:22Z",  "sandbox": true,  "last_checked_at": "2019-08-24T14:15:22Z",  "www_redirect": true,  "override_spf": true,  "validate_dmarc": true,  "validate_caa": true,  "monitor": true,  "batch_id": "string",  "end_user_ref": "string",  "client_label": "string",  "retried_at": "2019-08-24T14:15:22Z",  "routing": {    "mode": "edge",    "cname_target": "string",    "apex_ipv4": [      "string"    ],    "set_at": "2019-08-24T14:15:22Z"  },  "records_source": "integrator",  "created_via": "",  "secure_root_domain": true,  "redirect_to": "http://example.com",  "power_root_path_access": [    "string"  ],  "error_code": "string",  "error_message": "string",  "write_rail": "api_key",  "provider_account_id": "string",  "removal_started_at": "2019-08-24T14:15:22Z",  "dns_hosting": {    "state": "none",    "by": "customdomain",    "provider": "string",    "zone": "string",    "since": "2019-08-24T14:15:22Z"  },  "records": [    {      "type": "CNAME",      "host": "string",      "value": "string",      "ttl": 3600,      "priority": 0,      "applied": true,      "change": "created",      "prior": [        {          "type": "string",          "value": "string",          "ttl": 0,          "priority": 0        }      ],      "prior_source": "provider"    }  ],  "end_user_email": "[email protected]",  "ask_end_user_email": true,  "credential": {    "account_id": "string",    "provider": "string",    "status": "active",    "name": "string",    "scopes": [      "string"    ],    "account": "string",    "session_id": "string",    "verified_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z",    "notice": "d30",    "reconnect_reason": "expiring",    "reconnect_sent_at": "2019-08-24T14:15:22Z",    "renewed_at": "2019-08-24T14:15:22Z",    "old_key": "revoke_by_hand",    "revoke_url": "http://example.com",    "rights": [      "transfer"    ]  },  "reach": {    "kind": "account",    "account_id": "string",    "label": "string",    "provider": "string",    "can_reapply": true,    "managed_possible": true  }}

{  "id": "string",  "application_id": "string",  "domain": "string",  "host": "string",  "provider_id": "string",  "setup_type": "automatic",  "status": "pending",  "managed": true,  "created_at": "2019-08-24T14:15:22Z",  "sandbox": true,  "last_checked_at": "2019-08-24T14:15:22Z",  "www_redirect": true,  "override_spf": true,  "validate_dmarc": true,  "validate_caa": true,  "monitor": true,  "batch_id": "string",  "end_user_ref": "string",  "client_label": "string",  "retried_at": "2019-08-24T14:15:22Z",  "routing": {    "mode": "edge",    "cname_target": "string",    "apex_ipv4": [      "string"    ],    "set_at": "2019-08-24T14:15:22Z"  },  "records_source": "integrator",  "created_via": "",  "secure_root_domain": true,  "redirect_to": "http://example.com",  "power_root_path_access": [    "string"  ],  "error_code": "string",  "error_message": "string",  "write_rail": "api_key",  "provider_account_id": "string",  "removal_started_at": "2019-08-24T14:15:22Z",  "dns_hosting": {    "state": "none",    "by": "customdomain",    "provider": "string",    "zone": "string",    "since": "2019-08-24T14:15:22Z"  },  "records": [    {      "type": "CNAME",      "host": "string",      "value": "string",      "ttl": 3600,      "priority": 0,      "applied": true,      "change": "created",      "prior": [        {          "type": "string",          "value": "string",          "ttl": 0,          "priority": 0        }      ],      "prior_source": "provider"    }  ],  "end_user_email": "[email protected]",  "ask_end_user_email": true,  "credential": {    "account_id": "string",    "provider": "string",    "status": "active",    "name": "string",    "scopes": [      "string"    ],    "account": "string",    "session_id": "string",    "verified_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z",    "notice": "d30",    "reconnect_reason": "expiring",    "reconnect_sent_at": "2019-08-24T14:15:22Z",    "renewed_at": "2019-08-24T14:15:22Z",    "old_key": "revoke_by_hand",    "revoke_url": "http://example.com",    "rights": [      "transfer"    ]  },  "reach": {    "kind": "account",    "account_id": "string",    "label": "string",    "provider": "string",    "can_reapply": true,    "managed_possible": true  }}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "billing_required",  "title": "An active subscription is needed to connect new domains.",  "details": "This workspace has not started its subscription yet. Domains that are already connected keep working. An owner or admin can set up billing at https://app.customdomain.ai/app/billing."}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

Create a domain connection (idempotent per app + domain)

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

402application/json

403application/json

409application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`