Installation & embed

Mint a token on your server

The browser must never see an API key or a client_secret. Your server holds the credential, asks CustomDomain™ for a short-lived widget token (15 minutes), and hands only that token to the browser. Which credential you use depends on how the application was created.

Applications created in the console (every console signup gets one): use an API key. The application's client_secret is sealed in the console and is never shown anywhere, so POST /v1/tokens has nothing to authenticate with. Create a key on the API & SDK page (Create key; copy it when it is shown, it appears once), keep it in a server environment variable, and call the console's POST /api/widget-token:

// Your server route, for example POST /api/customdomain-token.
// Only signed-in users should reach it: add your own auth check.
const res = await fetch("https://app.customdomain.ai/api/widget-token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CUSTOMDOMAIN_API_KEY}`, // server only
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    application_id: "app_...", // optional: defaults to your first application
    domain: "app.customer.com", // optional: bind the token to one host
  }),
});
const { application_id, token } = await res.json();
// Return { application_id, token } to your own front end. Never the API key.

The response is 200 { "application_id", "token", "expires_in": 900, "token_type": "Bearer" }. The errors you can get back:

Applications created over the API (POST /v1/applications): that call returns the client_secret once. Keep it on your server and exchange it with POST /v1/tokens:

const res = await fetch("https://api.customdomain.ai/v1/tokens", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    application_id: process.env.CUSTOMDOMAIN_APPLICATION_ID,
    client_secret: process.env.CUSTOMDOMAIN_CLIENT_SECRET, // server only
    domain: "app.customer.com", // optional: bind to one host
  }),
});
const { token } = await res.json(); // 201, expires_in 900, scope "connect"

Do not put an API key in client_secret: /v1/tokens only accepts the application's own secret and answers 401 unknown application or secret. Do not rotate the client secret of a console-created application either: the console keeps its own copy and its widget preview and /api/widget-token stop working for that application.

What runs where:

See Widget tokens for the full token lifecycle, scopes and both mint paths.

Install and open

Pick one way to load the SDK.

getToken, wwwRedirect and onFallback need customdomain-js 0.5.0 or newer; removeDomain(), onRemoved and the customdomain:removed event need 0.5.2 or newer; CustomDomainError.status and the full checkDomain result need 0.5.4; the "reconnect" mode's types, reconnected and advisories need 0.5.5. The hosted script always has all of them.

import { customdomain } from "customdomain-js";
// (the hosted <script> build attaches window.customdomain instead)

// Asks your server (step 1) for a fresh widget token.
async function fetchToken() {
  const res = await fetch("/api/customdomain-token", { method: "POST" });
  if (!res.ok) throw new Error("Could not get a widget token");
  return res.json(); // { application_id, token }
}

document.getElementById("connect").addEventListener("click", async () => {
  const { application_id, token } = await fetchToken();

  customdomain.open({
    applicationId: application_id,
    token,
    getToken: async () => (await fetchToken()).token, // refresh during long setups
    domain: "app.customer.com", // optional prefill
    endUserRef: "user_42",      // your id for this customer
    // wwwRedirect: true,       // root domains: also connect www
    onSuccess: (r) => console.log("live:", r.domain, r.jobId, r.setupType),
    onFallback: (d) => console.log("manual:", d.reason),
    onClose: (d) => console.log("closed:", d.lastStatus),
    onStepChange: (d) => console.log("step:", d.step),
    onError: (err) => console.error(err.code, err.message),
  });
});

open() returns { close } so you can dismiss the modal programmatically. Only one modal is shown at a time. The default control-plane and widget hosts can be overridden with apiBase / widgetBase (e.g. for a staging environment).

onError receives a CustomDomainError: { code, message, details?, status? }. status is the HTTP status of the control plane response the error came from, and it is unset when the widget itself raised the error. A status of 429 or any 5xx is safe to retry after a moment; any other 4xx gives the same answer until the token, domain or records change. checkDomain and checkRecords throw the same class.

The options in the example above:

Every option, event and status is in the reference.