Quickstart
Use this path when you want to add customer custom-domain setup to a SaaS product and test the first hostname quickly.
What Custom Domain Kit Adds
Custom Domain Kit gives your product a hosted custom-domain setup flow. Your app keeps its own accounts, plans, permissions, tenant database, and runtime routing. Custom Domain Kit handles the domain setup UI, domain records, status refreshes, and status webhooks.
Four-step integration
- Create an app in the Custom Domain Kit dashboard and configure the webhook endpoint you will use in production.
- Add server endpoints in your SaaS app for setup sessions and webhook delivery.
- Embed
<custom-domainkit-setup>on the customer domain settings page. - Test one real customer hostname from setup through traffic and webhook delivery.
Required Values
You need these values before the browser renders the setup UI:
| Value | Where it comes from | Browser safe |
|---|---|---|
apiBaseUrl | Custom Domain Kit environment | Yes |
appId | Application created in Custom Domain Kit | Yes |
tenantId | Your product database | Yes |
actorId | Current operator in your product | Yes |
setupToken | Your server signs it with the app secret | Yes, short lived |
appSecret | Shown once when the app is created | No |
Recommended Reading Order
- Before you start
- Cloudflare connection modes
- Billing rules
- Create an App
- Server integration
- Frontend integration
- First test domain
Success Criteria
The quickstart is complete when:
- The app secret is stored only on your server.
- Your setup-session endpoint returns a fresh
cdk_st_...setup token. - The embedded setup UI can create a domain and show DNS records.
- The hostname reaches
active. - A browser request to the customer hostname reaches your SaaS origin.
- Your webhook receiver accepts a signed
domain.status_changedevent.