> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # DNS challenge for domain ownership > Verify domain ownership using a DNS TXT record to prevent unauthorized domain assignment across organizations. 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. > [!WARNING] > > Contact support to enable > DNS challenge verification is not enabled by default and is controlled by the `requires_domain_ownership` setting. Contact [support](https://docs.upsun.com/docs/overview/get-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. > [!NOTE] > > DNS challenges complement existing protections > The DNS challenge is an additional layer of security on top of the existing [Public Suffix List (PSL) approach](https://developer.upsun.com/docs/domains/steps/subdomains.md#how-domain-reservation-works). 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](https://developer.upsun.com/docs/domains/steps/subdomains.md#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 > [!NOTE] > > #### Legacy `_upsun-organization` records still work > > This challenge record was renamed from `_upsun-organization.` to `_domain-ownership.`. 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.` takes precedence. When you add a domain to a project, Upsun Cloud checks for a `TXT` record on a special subdomain: `_domain-ownership.`. The `TXT` record must contain your organization ID in the following format: ```text theme={null} organization= ``` You can retrieve your organization ID by running the following CLI command: ```bash Terminal theme={null} 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. > [!WARNING] > > 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: | Detail | Value | | - | - | | Domain to add | `app.example.com` | | Project ID | `abcdefg` | | Organization ID | `123456` | You would create the following `TXT` record: ```text theme={null} _domain-ownership.app.example.com TXT "organization=123456" # Do not remove ``` You can verify the record is in place by running: ```bash Terminal theme={null} dig +short _domain-ownership.app.example.com TXT ``` The `CNAME` configuration for the domain itself remains unchanged: ```bash Terminal theme={null} dig +short app.example.com CNAME main-bvxea6i-abcdefg.eu-3.platformsh.site. ``` ## 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: ```text theme={null} _domain-ownership.example.com TXT "organization=123456" # Do not remove ``` This record covers all subdomains under `example.com`. The platform stops checking as soon as it finds a valid challenge record. > [!NOTE] > > 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**: ```text theme={null} _domain-ownership.example.com TXT "organization=01234 organization=56789" # Do not remove ``` > [!WARNING] > > 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 setting | TXT record present | Behavior | | - | - | - | | `requires_domain_ownership`: **true** | Yes, valid | Domain is added successfully | | `requires_domain_ownership`: **true** | No or invalid | Domain is **rejected** | | `requires_domain_ownership`: **false** | Yes | TXT record is validated — domain is rejected if the org ID doesn't match | | `requires_domain_ownership`: **false** | No | Domain is added without challenge validation | ## 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: | Record type | Name | Value | | - | - | - | | `TXT` | `_domain-ownership.` | `organization=` | 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: ```bash Terminal theme={null} dig +short _domain-ownership. TXT ``` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.