From hostname to HTTPS

Four steps.
One live custom domain.

Your team declares where traffic should go. Your customer makes the DNS change. The lifecycle remains inspectable from creation to deletion.

Run the flow Open the quickstart

HTTPS destinationCustomer DNSManaged route

The responsibility is clear at every step.

The setup separates what your server does, what the customer changes and what the edge automates. That makes the flow easier to embed, support and recover.

Your server creates an HTTPS destination

Declare a public HTTPS URL. The first HTTPS destination becomes the default.

POST /v1/destinations
{ "url": "https://app.yoursaas.com" }

Your product creates the domain

Use the REST API, dashboard or a short-lived embedded widget session.

Idempotency-Key: customer-42-domain

Your customer updates DNS

Display the dns_records returned by creation, exactly as provided.

CNAME portal.acme.eu → in.subdomain.to

The edge validates and publishes

DNS is detected, the certificate is issued and the registered route becomes active.

pending_dns → validating → provisioning → active

Choose the right UX

API-led or embedded. Same domain model.

Both paths create the same customer-domain resource. Choose how much of the onboarding interface your product needs to own.

API-led

Your UI owns every state.

Choose this path when DNS instructions, lifecycle statuses and support actions must follow your product system exactly.

Browser: Your components
API key: Server only
Rendering: Your product

Embedded widget

Ship the input flow sooner.

Create a widget session on your server, then let the customer submit the hostname without exposing your API key.

Token: Expires after 1,800 seconds
Browser origin: Optional allowlist enforced
Created event: subdomain-to:created

Embedded path

Try the actual three-step widget.

Enter a sample domain. Demo mode stays in this browser and makes no API request.

Explore the widget integration →

Recovery is part of the lifecycle.

The happy path is not the only path. Secondary statuses keep DNS drift, provisioning failure, suspension and deletion explicit.

MISCONFIGURED

DNS drift

The domain can return to validation after the expected record is restored.

active → misconfigured → validating

FAILED

Provisioning stopped

The domain records the latest error instead of appearing indefinitely pending.

provisioning → failed

SUSPENDED

Traffic paused

A distinct status separates suspension from DNS or certificate problems.

active → suspended

DELETING

Removal accepted

Deletion returns 202 and moves the resource into an explicit terminal workflow.

* → deleting

Definition of live

Three subsystem statuses close the loop.

Do not infer readiness from DNS alone. Expose the branded URL only when the overall lifecycle is active and every required subsystem is operational.

DNSdns_status: valid
Certificatecertificate_status: issued
Routingrouting_status: active
Lifecyclestatus: active

Poll while onboarding

GET /v1/domains/{id}

{
  "data": {
    "status": "active",
    "dns_status": "valid",
    "certificate_status": "issued",
    "routing_status": "active"
  }
}

Implementation decisions

What your team still owns.

Where should the API key live?

Only on your server. For an in-product browser experience, issue a short-lived widget token server-side.

Should the UI poll?

You can retrieve GET /domains/{id} during onboarding. Webhooks currently cover hostname.created and hostname.deleting; use the resource status as the source of truth.

Do customers always add a CNAME?

No. Exact subdomains receive a CNAME. Apex domains receive one or more A records.

When is traffic routed?

Only after DNS validation and certificate provisioning. Unknown hostnames receive a 421 response at the edge.

Choose a starting point

Own the UI or run the flow first.

The quickstart covers the server-led path. The dashboard lets you inspect the same lifecycle before embedding it.

Follow the API quickstart Start in the dashboard

Four steps.One live custom domain.