Integrate with Domain Connect
Domain Connect is an open protocol for applying a known set of DNS records to a domain. A service publishes a JSON template, sends the user to their DNS provider, and passes the values required by that template. Domain Chief shows the proposed changes before writing any records.
This replaces instructions that ask users to copy DNS records by hand. It also gives the service a consistent setup flow across DNS providers that support Domain Connect.
Where this helps
Transactional email services such as Lettermint and workspace hosting services such as Cirrux often need MX, CNAME, TXT, or verification records. Domain Connect lets them describe those records once and send the user through an approval screen.
Integration flow
How a connection works
- Your service reads the domain's
_domainconnectTXT record to find its DNS provider. - Your service checks whether the provider has indexed your
providerIdandserviceIdtemplate. - Your service sends the user to the provider's apply URL with the domain and template parameters.
- Domain Chief validates the request and shows the records that will change.
- The user approves or cancels the changes.
- After approval, Domain Chief writes the records and returns the user to your service.
Supported flow
Domain Chief supports the synchronous interactive flow from Domain Connect v2. The domain owner must review and approve each request.
The asynchronous OAuth flow is not supported.
Publish and test a template
Publish a template
Domain Chief imports compatible templates from the official Domain Connect template repository each day. Publish your template there using the repository's standard file format. You do not need to ask Domain Chief to enable it.
The importer validates each template before indexing it. It skips templates that use unsupported records or options.
Your template must:
- Follow the Domain Connect v2 specification.
- Contain valid JSON and all required fields.
- Be available in the official template repository.
- Use records and template options supported by Domain Chief.
If you need to test a template before publishing it, email domainconnect@chief.app.
Test the integration
Use domainchief.app as the domain while testing your service's redirect and apply flow. It uses Domain Chief hosted DNS and can confirm whether an indexed template resolves correctly.
Test these outcomes before shipping:
- Domain Chief recognizes the template's
providerIdandserviceId. - Every required template parameter reaches the apply URL.
- A template with
hostRequired: trueincludes a non-emptyhostvalue. - The approval screen shows the expected additions, updates, and conflicts.
- The success and cancellation redirects return to the allowed domain from your template.
Application requirements and limits
Domain requirements
Domain Chief can apply a template only when:
- The domain is active in Domain Chief.
- The signed-in user has access to the domain.
- The domain uses Domain Chief hosted DNS.
- Domain Chief has indexed the requested template.
- The request supplies
hostwhen the template setshostRequiredtotrue.
If one of these conditions fails, Domain Chief reports the template or domain as unsupported instead of changing DNS.
Limits
- Domain Connect cannot apply records to domains using external nameservers.
- The protocol applies indexed templates. It does not expose an API for arbitrary DNS record changes.
- Domain Chief does not support the asynchronous OAuth flow.
Support
Email domainconnect@chief.app if Domain Chief does not recognize a published template or if you need to test one before it enters the public repository.