Create a domain connection (idempotent per app + domain)

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.

Authorization

widgetJWT

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. 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 rather than merge an existing SPF record.

Defaultfalse

validate_dmarc?boolean

Check DMARC as part of verification.

Defaultfalse

validate_caa?boolean

Check CAA before issuing certificates; also adds the two Let's Encrypt-authorizing apex CAA records to the connection's desired record set.

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.

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.

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",  "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",  "secure_root_domain": true,  "redirect_to": "http://example.com",  "power_root_path_access": [    "string"  ],  "error_code": "string",  "error_message": "string",  "records": [    {      "type": "CNAME",      "host": "string",      "value": "string",      "ttl": 3600,      "priority": 0,      "applied": 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",  "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",  "secure_root_domain": true,  "redirect_to": "http://example.com",  "power_root_path_access": [    "string"  ],  "error_code": "string",  "error_message": "string",  "records": [    {      "type": "CNAME",      "host": "string",      "value": "string",      "ttl": 3600,      "priority": 0,      "applied": true    }  ]}

{  "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

`application/json`

`application/json`

`application/json`

`application/json`