> ## 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 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>
  <h4>Feature flag required</h4>
  DNS challenge verification is currently behind a feature flag and is not enabled by default. If you want to use this feature, contact <a href="https://docs.upsun.com/docs/overview/get-support">support</a> to have it enabled for your project.
</Warning>

## 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.

<Info>
  <h4>DNS challenges complement existing protections</h4>
  The DNS challenge is an additional layer of security on top of the existing [Public Suffix List (PSL) approach](/docs/domains/steps/subdomains#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](/docs/domains/steps/subdomains#enable-subdomains-across-multiple-projects). The DNS challenge adds organizational ownership verification independently of that process.
</Info>

## 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-organization.<YOUR_DOMAIN>`. The `TXT` record must contain your organization ID in the following format:

```text theme={null}
organization=<YOUR_ORG_ID>
```

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>
  <h4>Keep the TXT record in place</h4>
  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.
</Warning>

### 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}
_upsun-organization.app.example.com  TXT  "organization=123456"
```

You can verify the record is in place by running:

```bash Terminal theme={null}
dig +short _upsun-organization.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 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}
_upsun-organization.example.com  TXT  "organization=123456"
```

This record covers all subdomains under `example.com`. The platform stops checking as soon as it finds a valid challenge record.

<Info>
  <h4>Public Suffix List</h4>
  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`.
</Info>

## 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}
_upsun-organization.example.com  TXT  "organization=01234 organization=56789"
```

<Warning>
  <h4>Use spaces only</h4>
  The separator between organization entries must be a space. Commas, semicolons, and newlines are not supported.
</Warning>

## 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                             |

<Info>
  <h4>Availability</h4>
  This feature is behind a feature flag. The <code>requires\_domain\_ownership</code> setting is currently managed by the Upsun internal team. To enable strict domain ownership verification for your project, contact <a href="https://docs.upsun.com/docs/overview/get-support">support</a>.
</Info>

## 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 type | Name                                | Value                        |
   | ----------- | ----------------------------------- | ---------------------------- |
   | `TXT`       | `_upsun-organization.<YOUR_DOMAIN>` | `organization=<YOUR_ORG_ID>` |

   To cover all subdomains under a parent domain, set the record at the parent level (e.g. `_upsun-organization.example.com`).

3. Wait for DNS propagation, then verify the record:

   ```bash Terminal theme={null}
   dig +short _upsun-organization.<YOUR_DOMAIN> TXT
   ```

4. Add your domain to your Upsun project as usual. The platform automatically validates the challenge record during this step.