The same DNS guidance. Two ways to make it yours.
Both options detect the DNS provider, explain which records to add, and check whether the values match. Choose how much of the interface you want to build.
Ready-made interface
Embed the widget
Add a complete setup flow to your domain settings page with JavaScript and CSS. Use the supplied styles or adjust them to fit your product.
- Domain entry, instructions, and verification included
- Customizable styles, with no iframe required
- Events to keep the rest of your interface in sync
Your own interface
Build with headless mode
Get the provider details, record values, and setup steps as JSON. Display them in your own components, with control over the layout, styling, and copy.
- Ordered instructions with provider-specific field labels
- DNS verification results to display your way
- A small browser client, or direct calls from your backend
See the setup experience
Explore the embeddable widget’s CSS styles, or try a custom interface with the React and Vue starters. No installation needed.
The demos use sample records. Your integration supplies the records for your application.
A clear next step, from domain to DNS check
01
Start with their domain
Ask the customer for a domain, or pass in one your app already knows. You choose the records they need.
02
Guide the DNS changes
Show instructions for their provider, including the names and values to enter. Offer automatic setup when a supported integration is available.
03
Check what matches
Let customers check their changes and see which records still need attention, without leaving your setup flow.
Instructions that fit their DNS provider
A field called “Host” in one dashboard might be called “Name” in another. The instructions use the provider’s labels and display values, so customers know what goes where.
When provider-specific instructions aren’t available, customers get general DNS instructions. Automatic setup is offered only when a supported provider integration is available.
The records your app needs
- A records
- Point a domain to your cluster’s IPv4 address.
- CNAME records
- Point a subdomain to a hostname your app controls.
- TXT records
- Publish a value for your app to check, such as a domain verification code.
Fits into your domain settings page
Use your product’s look and feel
Adjust the embeddable widget’s colors, spacing, and typography with CSS. For a fully custom layout, use headless mode with the components you already have.
Explore styling optionsKeep customers informed
Show which records match and let customers retry after making changes. DNS verification is one step in connecting a domain; your app can then check routing and HTTPS before marking it ready.
Read about verificationView a complete embed example
1. Create a scoped token on your server.
Add an authenticated GET /api/dns-widget-token endpoint to your application. Require the appropriate permission to manage domains, call the helper below on the server, and return its result as JSON with Cache-Control: no-store. That application endpoint is yours to implement; it is not an Approximated endpoint.
// Server only: call from your authenticated application endpoint.
export async function getDnsWidgetToken() {
const apiKey = process.env.APX_API_KEY;
if (!apiKey) throw new Error("APX_API_KEY is not configured");
const response = await fetch(
"https://cloud.approximated.app/api/dns/v2/token",
{ method: "GET", headers: { "api-key": apiKey }, cache: "no-store" }
);
if (!response.ok) throw new Error("Unable to initialize DNS setup");
const data = await response.json();
if (typeof data.token !== "string" || data.token.length === 0) {
throw new Error("DNS setup returned an invalid token");
}
return { token: data.token };
}Keep the cluster API key on the server. The browser receives a temporary pass tied to that key. The widget can renew it for up to 24 hours; deleting or replacing the key stops those passes from working. See scoped tokens for lifetimes and request limits.
2. Load the widget in your domain settings page.
Replace 192.0.2.10, a documentation-only address, with your assigned cluster IPv4 address. Place this markup in the page where customers configure a domain. Initialize it once after the container is present.
<link
rel="stylesheet"
href="https://cloud.approximated.app/dnswidget/dnswidget.v2.css"
>
<div id="apxdnswidget" class="apxdnswidget"></div>
<p id="dns-widget-status" role="status"></p>
<script src="https://cloud.approximated.app/dnswidget/headless.v2.js"></script>
<script src="https://cloud.approximated.app/dnswidget/dnswidget.v2.js"></script>
<script type="module">
const status = document.getElementById("dns-widget-status");
document.addEventListener(
"apx-dnswidget-records-completely-verified",
() => {
status.textContent = "DNS records match.";
}
);
try {
const response = await fetch("/api/dns-widget-token", {
credentials: "same-origin",
cache: "no-store"
});
if (!response.ok) throw new Error("Unable to start DNS setup");
const { token } = await response.json();
if (typeof token !== "string" || !token) {
throw new Error("Invalid DNS setup token");
}
window.apxDns.init({
token,
api_url: "https://cloud.approximated.app/api/dns/v2",
dnsRecords: [
{ type: "A", host: "@", value: "192.0.2.10", ttl: 3600 }
],
verifyAutoScroll: false
});
} catch {
status.textContent =
"DNS setup could not start. Refresh the page to try again.";
}
</script>Set prefillDomain if you want to prefill the domain entry field. Set domain when your application already has the domain and should skip that step. For client-side navigation, mount the widget after its container exists and manage its lifecycle as described in the integration docs.
3. Connect verification to your domain lifecycle.
The widget emits events for complete, partial, and failed record verification. Use them to update the interface, then let your backend check the expected domain and tenant before advancing its state. The example above only updates a status message. DNS verification does not establish that a virtual host has been created or that HTTPS is ready. Widget events, domain lifecycle.
A few things you might be wondering
- Can I use it with my framework?
- Yes. The widget uses plain JavaScript and CSS. Headless mode returns JSON you can render in any framework. Browser integrations use a short-lived token created by your backend.
- Does it update DNS automatically?
- For supported integrations, it offers a setup link that takes the customer through their provider’s approval flow. Manual instructions are available when automatic setup isn’t offered.
- What if I already know the customer’s domain?
- Pass it to the widget to skip domain entry, or prefill the field so the customer can edit it. With headless mode, your app controls that step.
- What if the records don’t match yet?
- Show the values found in DNS so the customer can check their work. DNS caching can delay updates; keep the setup flow available so they can check again.
Make connecting a domain part of your product.
Start with the ready-made widget, or bring the same DNS guidance into a flow you design.