> For the complete documentation index, see [llms.txt](https://help.tahua.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tahua.io/product-news/2026/june/configurable-api-base-domain.md).

# Configurable API base domain

## Problem

The OAuth2 API serves requests on the same domain as the web UI (e.g., `tenant.tahua.io/api/v2/...`). As API usage grows, separating API traffic onto a dedicated domain prevents a painful migration later when infrastructure needs to be split.

## How it works

A new environment variable `API_WILDCARD_DOMAIN` enables a dedicated API domain pattern. When set (e.g., `api.tahua.io`), API URLs become `{tenant}.api.tahua.io` and bidirectional domain enforcement applies:

* **API domain** (`tenant.api.tahua.io`): Only serves API paths (`/api/...`) and OAuth paths (`/oauth/...`). All other paths return a `404 Not Found` JSON response.
* **Web domain** (`tenant.tahua.io`): Rejects API and OAuth paths with a `421 Misdirected Request` JSON response that includes the correct `api_base_url`, guiding clients to the right domain.

When `API_WILDCARD_DOMAIN` is not set, everything works exactly as before with no enforcement — full backwards compatibility.

## UI changes

The **Admin Settings > API Access** application detail page now displays the API-specific base URL for the token endpoint and curl example when `API_WILDCARD_DOMAIN` is configured. This ensures administrators copy the correct domain when setting up API integrations.

## Configuration

Set the `API_WILDCARD_DOMAIN` environment variable to enable the feature:

```
API_WILDCARD_DOMAIN=api.tahua.io
```

No DNS or SSL changes are handled by this feature — those are a separate infrastructure concern.
