When to use DNS challenges
DNS challenges are especially recommended 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’s infrastructure could be assigned to a project belonging to a different organization. This allows that organization to receive traffic intended for the legitimate domain owner. For example, if you remove a domain from one project but its DNS records still point to Upsun, another organization could add that domain to their own project and intercept its traffic. The DNS challenge ensures that only the organization that controls the domain’s DNS records can add that domain to their project.How it works
When you add a domain to a project, Upsun checks for aTXT record on a special subdomain: _upsun-organization.<YOUR_DOMAIN>. The TXT record must contain your organization ID in the following format:
Terminal
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.
Example
For a project with the following details:
You would create the following
TXT record:
Terminal
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 walks up the domain hierarchy — from the full domain toward the apex — until it finds a valid challenge record. For example, to allow bothapp.example.com and api.example.com to be added to the same organization, you can create a single record at the parent domain level:
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 singleTXT record. Separate each entry with a space:
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:Availability
This feature is behind a feature flag. Therequires_domain_ownership setting is currently managed by the Upsun internal team. To enable strict domain ownership verification for your project, contact support.Set up a DNS challenge
To set up domain ownership verification, follow these steps:- Find your organization ID in the Upsun Console under your organization settings.
-
Create a
TXTrecord with your DNS provider:To cover all subdomains under a parent domain, set the record at the parent level (e.g._upsun-organization.example.com). -
Wait for DNS propagation, then verify the record:
Terminal
- Add your domain to your Upsun project as usual. The platform automatically validates the challenge record during this step.