A DNS setup widget for your SaaS

See the customer flow

1. 1. Enter a domain.

   Let the customer enter their domain or prefill one your application already knows.

2. 2. Get the relevant setup steps.

   The widget identifies the DNS provider and displays the requested records. Supported integrations can offer an automatic setup link; manual instructions are available for the customer to follow.

3. 3. Check the result.

   The customer runs verification to see which requested records match and which still need attention.

The live demo uses sample destination records. It demonstrates the interface; your integration supplies the records for your own application. A DNS match is separate from a working TLS certificate and a successful request to your app.

Provider guidance with a manual path

The widget adapts the setup instructions to the detected provider and requested records. Automation depends on the provider and the supported integration; it is not available for every DNS host or configuration. Provider approval, when offered, happens through the provider’s flow. Setup behavior.

If the customer uses the manual path, they see the record name, type, and value to enter. After making changes, they can return to verification. If a record still does not match, the verification view shows the observed result so they can check the value and allow for DNS caching.

Configure the records your application needs

The widget accepts A, CNAME, and TXT records. You provide the record type, host, value, and TTL for the setup you want customers to complete. Supported configuration.

Only request records relevant to the chosen connection. For example, choose the appropriate A or CNAME configuration for an address; do not ask the customer to create both at the same DNS name. Your application determines what a verified TXT value means for domain ownership or another workflow.

Embed it with a small amount of JavaScript

The widget uses a JavaScript file and CSS stylesheet. It renders into your page and does not require an iframe. The following example starts an apex A-record flow. Embedding documentation.

1. Mint a short-lived 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/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 the short-lived widget token. See the token endpoint for the API contract.

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.v1.css"
>
<div id="apxdnswidget" class="apxdnswidget"></div>
<p id="dns-widget-status" role="status"></p>
<script src="https://cloud.approximated.app/dnswidget/dnswidget.v1.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",
      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.

Match your product’s styling

Override the widget’s scoped CSS variables and styles to fit your settings page. For example:

.apxdnswidget {
  width: 100%;
  max-width: 100%;
  --widget-max-width: 100%;
  --text-color: #20242a;
  --light-text-color: #4b5563;
  --button-bg-color: #20242a;
  --button-text-color: #ffffff;
  --radius: 8px;
}

Start with the supplied stylesheet and check the flow at your settings panel’s desktop and mobile widths. See the styling options.

Handle the states customers actually see

Tokens last approximately ten minutes. The widget attempts to renew its token while the page is open; if the session expires, start again with a newly minted token. The token allows widget API access; it is not your application’s domain-ownership or tenant-authorization check. Token lifecycle.

Frequently asked questions

Does it automatically update every provider?

No. Automatic setup is offered where a supported integration is available. The provider-specific manual flow remains part of the customer experience.

Can I use it with my existing framework?

The widget is plain JavaScript and CSS. You need a page container and a backend that can mint its token. You can include it in an application built with frameworks such as Next.js, Laravel, Rails, or Phoenix; the surrounding domain and tenant lifecycle belongs to your application.

Will a successful DNS check make HTTPS ready?

It confirms that the requested records match the lookup results. Your application should check the domain’s TLS and routing state separately before reporting it as connected.

Can I supply the domain instead of asking the customer to type it?

Yes. The domain option skips domain entry, while prefillDomain fills the entry field and leaves the step visible. Configuration options.