Connect flow
Overview
The create → apply → live pipeline and the four rails that write DNS.
Connecting a domain is a short pipeline on top of the connection lifecycle:
- Create a connection —
POST /v1/connectionsstarts the process and returns the connection plus its authoritative desired DNS records. - Apply the records — pick a rail (below) to get the records into the customer's DNS.
- Go live — the propagation poller promotes the connection to
liveonce every desired record resolves; the edge then issues TLS on the next handshake and you receive aconnection.livewebhook. - Offboarding — how a domain is removed.
The four rails
A connection reaches live through one of four rails. The best available one is
chosen from POST /v1/domains:check; the widget drives them automatically.
| Rail | Endpoint | How it applies records |
|---|---|---|
| OAuth into provider (flagship, "Mode C") | POST /v1/connections/{id}/oauth:start → GET /v1/connect/oauth/callback | Customer authorizes with their DNS provider in a popup; the callback writes records with a one-time token, never stored. |
| Domain Connect (sync + async) | POST /v1/connections/{id}/domainconnect:start | Returns a provider-hosted apply URL; the provider applies a signed template. No server-to-server token. |
| API token (BYO) | POST /v1/connections/{id}/apply | You pass a scoped provider token in the request; it writes the records once and is discarded. |
| Manual | (none — just the record set) | Customer copies the records from GET /v1/connections/{id}/records; the poller waits for them to appear. |
All four converge on the same outcome: the desired records land in DNS, the
connection moves pending → propagating → live, and the edge serves the domain.
For the fastest path with real curl, see the
Quickstart. To let customers drive the flow
themselves, embed the widget. What each rail needs
operationally is covered in DNS providers.