Setup types & the ask gate

Setup types

POST /v1/domains:check classifies a domain into a setup_type that steers the widget to the smoothest available rail:

• automatic — the provider can be configured without the customer copying records: an OAuth-into-provider authorization or a one-click setup apply. domains:check reports oauth_available and domain_connect so the widget knows which is on offer.
• manual — no automatic path; the customer copies the exact records into their DNS provider and the poller watches for them.
• async — a one-click setup flow that completes out-of-band (the provider applies the template after a redirect). This is also the rail that powers managed connections: start it with POST /v1/connections/{id}/domainconnect:start and {"managed": true} (or {"rail":"async"}) to get an async consent URL, and the callback (GET /v1/connect/dc/callback) exchanges the code for a durable, encrypted grant so the platform can re-apply and revert the template server-side later. When the provider does not support the async variant, the call falls back to the sync apply_url and the connection stays use-once.
• mcp — reserved for agent-driven setup.

The engine also returns capability flags (ns_support, wildcard_support, cname_flattening, spf_override_support, caa_support) and any record_conflicts it observes in public DNS, so you can pre-warn the customer.

Entering a domain

The console mirrors exactly what you type. Enter www.acme.com and it connects www.acme.com, a subdomain, matching what the widget and the API do. It is never silently rewritten to the apex acme.com.

If you type a subdomain, the connect page also offers the root domain as a one tap chip ("Meant the root domain? Use acme.com"), so switching to the apex is a visible choice, not a guess the platform makes for you.

This also affects the www redirect: connecting the apex acme.com shows an opt in checkbox, "Also redirect www.acme.com", off by default. Turn it on if you want www.acme.com to redirect to the apex once both are live.

Control is proven by the rail

There is no separate ownership-TXT challenge. Each rail is itself proof that the customer controls the zone:

• an OAuth authorization grants a one-time token to that customer's DNS account;
• a one-click setup apply happens inside the customer's provider session; its async (managed) variant additionally leaves a durable, encrypted grant — the one credential the platform keeps, and only to re-apply or revert that same template;
• an API token is a scoped credential only the zone owner can mint;
• the manual flow requires the records to actually appear in the domain's authoritative DNS, value-checked.

For one-click setup specifically, the catalog ships a connect-verified template that points the apex A at the Customdomain edge and publishes the ownership TXT token together, applied atomically so serving and proof-of-control go live in one step (a verify-only template publishes just the token). The token record is flagged essential: OnApply, so applying the template that carries it is itself the ownership proof.

Optional credential reuse

By default an API-token credential is used once for the apply and then discarded. Optionally, when connecting in the console you can tick "Remember this key" to save that provider key for reuse. It is off by default and opt-in per key.

A remembered key is encrypted at rest (AES-256-GCM, scoped to one tenant + provider) and its plaintext never leaves the server. On the next connect at that provider, "Use saved key" applies records in one click without re-entering anything, and for Cloudflare / GoDaddy / Route 53 / Namecheap the same key can bulk-connect the account's other domains. Revoke a saved key any time under Settings → Connected provider accounts. See Provider setup and Security.

The ask gate

Before the edge serves TLS for a hostname, it calls POST /internal/ask. The control-plane approves the host iff a connection for it is live or propagating — a status-based gate, answered from a single indexed lookup so the TLS handshake never blocks on business logic. A domain the platform has never connected is refused, so the edge will never obtain a certificate for an unauthorized host.