Skip to content

Knowledgebase

Create a forwarding domain and complete DNS ownership verification

domain-nexus, development

Create a forwarding domain when you want the configured runtime to redirect web requests, forward incoming mail or provide both services. Confirm that the account and product include the required forwarding feature before changing a working website or mail route.

Method Resource Scope Idempotency-Key
POST /v2/forwarding/domains forwarding:write Required
GET /v2/forwarding/domains/{domainId} forwarding:read Not required by this route
POST /v2/forwarding/domains/{domainId}/verify-dns forwarding:write Required
GET /v2/forwarding/domains/{domainId}/conflicts forwarding:read Not required by this route

01 Onboard and prove control

  1. List existing forwarding domains to avoid a duplicate claim. Confirm the registered-domain reference if linking an owned domain.
  2. POST the full domain and choose forwarding_type as http, mail or both. Supply a cluster reference only when that runtime is eligible and assigned to your account.
  3. Save the returned forwarding-domain ID. A newly created record starts in a pending DNS state.
  4. Open the domain's current setup instructions in DNS Manager and read the detail and conflicts. Copy the issued ownership challenge and the actual runtime DNS destinations.
  5. Publish the challenge at the authoritative DNS provider. The current challenge uses _domain-verify and an issued domain-verification=... TXT value. Use the exact value for this domain, not the example or another account's token.
  6. Check the authoritative answer, then request verify-dns. Track verification and subsequent deployment separately.

02 Preserve existing services

HTTP forwarding needs requests to reach its configured runtime. Mail forwarding needs the appropriate mail routing. Those changes can replace the destination of an existing website or inbox service. Resolve reported hosting, MX or ownership conflicts and agree the intended service before applying them.

The conflicts endpoint shows recorded evidence. If you change hosting or DNS, run the relevant verification again rather than assuming an old clean result remains valid. Creating a forwarding-domain row does not itself create a website, mailbox or complete deployment.

Common questions

Why does the domain resolve but verification still fail?

Normal A, AAAA or MX records do not prove that you published the exact ownership nonce. Check the TXT name, full value and authoritative provider.

Can I use a cluster belonging to another account?

No. Cluster selection remains subject to tenant and service assignment checks.

Does deleting the forwarding domain immediately remove every remote component?

Deletion enters a workflow. Check the resulting runtime, DNS and certificate state before declaring the service fully removed or reassigning the hostname.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support