Skip to content

fix: clarify Turnstile hostname management subdomain behavior #29752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
patriciasantaana merged 2 commits into from
Apr 27, 2026
Merged

fix: clarify Turnstile hostname management subdomain behavior #29752

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6fbb51
fix: clarify Turnstile hostname management subdomain behavior
zeinjaber Apr 10, 2026
af9005b
Apply suggestion from @patriciasantaana
patriciasantaana Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 21 additions & 6 deletions src/content/docs/turnstile/additional-configuration/hostname-management/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ By default, every widget requires at least one hostname to be configured. You ca
When adding hostnames, follow these requirements:

- The hostname must be fully qualified domain names (FQDNs): `example.com` or `subdomain.example.com`
- No wildcards are supported. You must specify each hostname individually.
- Wildcard characters (such as `*`) are not supported in the hostname field. However, adding a hostname automatically authorizes all of its subdomains.

:::caution[Invalid formats]
The following formats are not valid and will not be accepted:
Expand All @@ -37,19 +37,34 @@ The following formats are not valid and will not be accepted:

### Subdomain behavior

Specifying a subdomain provides additional security by restricting widget usage.
When you add a hostname, the widget will work on that exact hostname and all of its subdomains. This means adding a root domain covers all subdomains beneath it, while adding a specific subdomain restricts the widget to only that subdomain and its children.

For example, adding `www.example.com` as a hostname will allow widgets to work on:
#### Example: Root domain

Adding `example.com` as a hostname will allow the widget to work on:

- `example.com`
- `www.example.com`
- `abc.www.example.com:8080` (subdomains of the specified hostname).
- `shop.example.com`
- `any.sub.example.com`

#### Example: Specific subdomain

However, it will not work on:
Adding `www.example.com` as a hostname provides more restrictive control. The widget will work on:

- `www.example.com`
- `abc.www.example.com` (subdomains of the specified hostname)

However, it will **not** work on:

- `example.com` (parent domain)
- `dash.example.com` (sibling subdomain)
- `cloudflare.com` (unrelated domain)

:::note
Use a specific subdomain when you want to restrict the widget to a narrower scope. For example, if you only want the widget on your checkout flow, add `checkout.example.com` rather than `example.com`.
:::

## Add hostnames

<Tabs>
Expand Down Expand Up @@ -97,4 +112,4 @@ However, it will not work on:

Free users are entitled to a maximum of 10 hostnames per widget.

Enterprise customers can have up to 200 hostnames per widget.
Enterprise customers can have up to 200 hostnames per widget.
Loading