Installation & embed
Load the hosted bundle, mint a widget token server-side, and open the modal.
Load the hosted bundle and open the modal with a token minted by your backend:
<script src="https://connectdomain.app/sdk/v1/connectdomain.js"></script>
<button id="connect">Connect your domain</button>
<script>
document.getElementById('connect').addEventListener('click', async () => {
// Fetch a fresh token from YOUR backend (which calls POST /v1/tokens with
// your API key). Never ship the API key to the browser.
const { application_id, token } = await fetch('/my-backend/mint-widget-token', {
method: 'POST',
}).then((r) => r.json());
window.connectdomain.open({
applicationId: application_id,
token,
brandName: 'Your App',
email: true, // optional: offer email (MX/SPF/DKIM/DMARC) setup after connect
onSuccess: (r) => console.log('domain live', r.domain),
onClose: (r) => console.log('closed', r.succeeded),
});
});
</script>Email setup
Pass email: true to add an optional step after the domain connects: the user
picks their mailbox provider (Google Workspace, Microsoft 365, or Zoho) and the
widget writes the MX/DKIM/DMARC records via your delegated DNS credential,
showing the apex SPF record to add manually (so it never clobbers an existing
one). See Email DNS for the underlying API.
window.connectdomain.open() is the canonical entry point; showConnect() is a
kept alias, and window.customdomain still points at the same object for the
pre-rename API. baseUrl defaults to https://api.connectdomain.app — override
it only when self-hosting the control plane.
Signed-in users can grab their applicationId, mint a live test token, and copy
a ready-to-paste snippet from the Embed tab in the dashboard.
White-label theming
Pass a theme object to match your brand. All fields are optional:
window.connectdomain.open({
applicationId, token,
theme: {
accentColor: '#0ea5e9', // buttons + progress
accentTextColor: '#ffffff',
background: '#ffffff',
foreground: '#111827',
radius: '10px',
logoUrl: 'https://yourcdn.example/logo.svg', // header logo
hideBranding: true, // hide the "Secured by Connect Domain" mark
},
});Theme values are applied as CSS custom properties on the widget's shadow host,
so they never leak into your page. You can also override the properties directly
in CSS on #connectdomain-widget-root (--cd-brand, --cd-bg, --cd-fg,
--cd-radius, …).