Skip to main content
When you add a domain to a Upsun 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.

Feature flag required

DNS challenge verification is currently behind a feature flag and is not enabled by default. If you want to use this feature, contact support to have it enabled for your project.

​
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. You still need to follow the steps described in Enable subdomains across multiple projects to share subdomains between projects. The DNS challenge adds organizational ownership verification on top 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 a TXT record on a special subdomain: _upsun-challenge.<your-domain>. The TXT record must contain your organization ID in the following format: 
organization=<orgID>
You can retrieve your organization ID by running the following CLI command:
Terminal
upsun organization:info --format plain
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’s servers. It is not a one-time verification. The platform may re-check the record, and removing it while the domain is still active could cause issues.

​
Example

For a project with the following details:
DetailValue
Domain to adddomain.example.org
Project IDabcdefg
Organization ID123456
You would create the following TXT record: 
_upsun-challenge.domain.example.org  TXT  "organization=123456"
You can verify the record is in place by running:
Terminal
dig +short _upsun-challenge.domain.example.org TXT
The CNAME configuration for the domain itself remains unchanged:
Terminal
dig +short domain.example.org CNAME
main-bvxea6i-abcdefg.eu-3.platformsh.site.

​
Subdomain trimming

You don’t need to create a separate challenge record for every subdomain. Upsun trims subdomains upward until it finds a valid challenge record. For example, to allow both foo.example.org and bar.example.org to be added to the same organization, you can create a single record at the parent domain level: 
_upsun-challenge.example.org  TXT  "organization=123456"
This record covers all subdomains under example.org. 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: 
_upsun-challenge.example.org  TXT  "organization=01234 organization=56789"

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:
Project settingTXT record presentBehavior
requires_domain_ownership: trueYes, validDomain is added successfully
requires_domain_ownership: trueNo or invalidDomain is rejected
requires_domain_ownership: falseYesTXT record is validated — domain is rejected if the org ID doesn’t match
requires_domain_ownership: falseNoDomain is added without challenge validation

Availability

This feature is behind a feature flag. The requires_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:
  1. Find your organization ID in the Upsun Console under your organization settings.
  2. Create a TXT record with your DNS provider:
    Record typeNameValue
    TXT_upsun-challenge.<your-domain>organization=<your-org-id>
    To cover all subdomains under a parent domain, set the record at the parent level (e.g. _upsun-challenge.example.org).
  3. Wait for DNS propagation, then verify the record:
    Terminal
    dig +short _upsun-challenge.<your-domain> TXT
  4. Add your domain to your Upsun project as usual. The platform automatically validates the challenge record during this step.
Last modified on March 27, 2026