Skip to main content
When DNS challenge verification is enabled and you add a domain to an Upsun Cloud project, the platform performs a DNS challenge to verify that your organization owns the domain. This prevents another organization from claiming your domain and intercepting its traffic.

Contact support to enable

DNS challenge verification is not enabled by default and is controlled by the requires_domain_ownership setting. Contact support to have it enabled for your project.

​
When to use DNS challenges

Consider using DNS challenges when you share a domain across multiple projects. If different projects within your organization use subdomains of the same apex domain (for example, app.example.com and api.example.com), setting up a DNS challenge ensures that no other organization can claim any of those subdomains.

DNS challenges complement existing protections

The DNS challenge is an additional layer of security on top of the existing Public Suffix List (PSL) approach. It does not replace it. If you are also sharing subdomains across multiple projects, you still need to follow the steps in Enable subdomains across multiple projects. The DNS challenge adds organizational ownership verification independently of that process.

​
Why DNS challenges exist

Without ownership verification, a domain whose DNS still points to Upsun Cloud’s infrastructure could be claimed by a different organization’s project, letting that organization receive traffic meant for the legitimate owner. This can happen, for example, if you remove a domain from one project but leave its DNS records pointing to Upsun Cloud. The DNS challenge ensures only the organization that controls a domain’s DNS records can add it to a project.

​
How it works

​
Legacy _upsun-organization records still work

This challenge record was renamed from _upsun-organization.<YOUR_DOMAIN> to _domain-ownership.<YOUR_DOMAIN>. If you’re still using the legacy _upsun-organization name, update to _domain-ownership when convenient. The platform continues to honor the legacy name, so this isn’t urgent.If both records exist for the same domain, _domain-ownership.<YOUR_DOMAIN> takes precedence.
When you add a domain to a project, Upsun Cloud checks for a TXT record on a special subdomain: _domain-ownership.<YOUR_DOMAIN>. The TXT record must contain your organization ID in the following format:
You can retrieve your organization ID by running the following CLI command:
Terminal
The id field in the response is the value to use in the TXT record. If the organization ID in the TXT record doesn’t match the organization that owns the project, the domain is rejected.

Keep the TXT record in place

The TXT record must remain in your DNS for as long as the domain points to Upsun Cloud’s servers. The platform re-checks it periodically, so removing it while the domain is active can cause issues.

​
Example

For a project with the following details: You would create the following TXT record:
You can verify the record is in place by running:
Terminal
The CNAME configuration for the domain itself remains unchanged:
Terminal

​
Subdomain trimming

You don’t need to create a separate challenge record for every subdomain. Upsun Cloud walks up the domain hierarchy, from the full domain toward the apex, until it finds a valid challenge record. For example, to allow both app.example.com and api.example.com to be added to the same organization, you can create a single record at the parent domain level:
This record covers all subdomains under example.com. The platform stops checking as soon as it finds a valid challenge record.

Public Suffix List

The trimming process respects the Public Suffix List (PSL). The platform won’t look for challenge records on public suffixes like .org or .co.uk.

​
Multiple organizations

If you need to allow multiple organizations to add subdomains under the same parent domain, you can include multiple organization IDs in a single TXT record. Separate each entry with a space:

Use spaces only

The separator between organization entries must be a space. Commas, semicolons, and newlines are not supported.

​
Validation behavior

The DNS challenge check runs every time a domain is added to a project, regardless of whether the feature is explicitly enabled. However, how the result is enforced depends on the project’s configuration:

​
Set up a DNS challenge

To set up domain ownership verification, follow these steps:
  1. Find your organization ID in the Upsun Cloud Console under your organization settings.
  2. Create a TXT record with your DNS provider: To cover all subdomains under a parent domain, set the record at the parent level (e.g. _domain-ownership.example.com).
  3. Wait for DNS propagation, then verify the record:
    Terminal
  4. Add your domain to your Upsun Cloud project as usual. The platform automatically validates the challenge record during this step. Leave the TXT record in place afterwards. It is checked again every time you add another domain or subdomain.
Last modified on September 15, 2026