The connect flow

Every connect session resolves to one URL: https://app.dodomain.io/connect/<token>. You can hand that link to your user directly (zero code on your frontend) or open the same flow in a modal on your own page with the @dodomain/connect widget.

Provider detection

When the user lands on the connect page, DoDomain detects which DNS provider manages the domain and picks the best available path for that provider. The session's detect endpoint (POST /api/v1/sessions/:token/detect) powers this — it identifies the provider, the registrable zone, and the nameservers.

Connect tiers

• Cloudflare one-click — for domains on Cloudflare, the user grants a scoped OAuth consent and DoDomain writes the records for them, verifies via the Cloudflare API, and then deletes its token. A real one-click.
• Guided manual — the universal fallback for every other provider: provider-specific deep links plus copy-paste instructions for each record, with live per-record verification so the user sees each record turn green as it propagates.

Whatever the path, verification is always done against the domain's authoritative nameservers — not a cache — so a green result means the records are really live.

One-click is a Pro and Scale feature

One-click setup (Cloudflare OAuth, and Domain Connect where the user's provider has enabled it) is offered on sessions created by a Pro or Scale team. A Free team's sessions use the guided manual flow for every provider: the page shows no one-click button, and the one-click start routes answer 403 forbidden. Your users never see plan or upgrade copy — only the records and the verify step.

The offer is decided when the session is created and does not change afterwards. Upgrade and every new session offers one-click; a session that was already open keeps the flow it started with, and a downgrade does not take one-click away from a session already in progress.

The widget

@dodomain/connect is an embeddable browser widget: a modal iframe over the hosted flow, so your user never leaves your page.

import { showDoDomain } from "@dodomain/connect";

// token comes from your server's POST /api/v1/sessions call
showDoDomain({ token: session.token, onVerified: () => location.reload() });

Install with npm install @dodomain/connect. The widget is MIT-licensed with zero runtime dependencies. It also reports where the user got to when the modal closes, and tells you when the iframe could not mount at all so you can fall back to the hosted link — see Embed the connect flow for every option and callback.

Sharing the setup with a DNS admin

The person holding the connect link is often not the person who can edit DNS. On the hosted page, Create a link for your DNS admin mints a second, narrower link (https://app.dodomain.io/setup/<token>) they can forward. Whoever opens it sees your branding, the domain, the exact records and a Verify button — nothing else: no one-click flow, no return into your product, and never the session token. It expires with the session, creating a new one replaces the previous one, and a verify pressed from it completes the connection and fires the same webhooks as the hosted page. The same mint is available server-side as POST /api/v1/sessions/:token/shared-setup-link. Not available inside the embedded widget.

Sessions are short-lived capabilities

A session token (dd_sess_...) is a single-session bearer capability: whoever holds it can read that session and trigger its verification. It travels inside connectUrl by design and is safe to hand to the browser — but treat it like a password-reset link: keep it out of logs and analytics, and send it only to the user doing the connecting. Sessions expire 24 hours after creation; after expiry every token-authorized session endpoint answers 410 expired, and an expired session can never be verified. Your own server can still read what happened to it with GET /api/v1/sessions/:id and your secret key.

SSL

DoDomain writes and verifies the DNS that points a customer's domain at your infrastructure — TLS terminates at your host (Vercel, Cloudflare for SaaS, Caddy, nginx, and similar setups). DoDomain does not proxy traffic or issue certificates for you.