docs: update knowledge gap from thread 1512031509387673610 (#12328)

Automatically generated PR targeting 1 files. **Thread ID:** 1512031509387673610 **Action:** UPDATE **AI Summary:** > The documentation lacks clear explanation of how the 'Use new login UI' checkbox and 'Custom base URL for the new Login UI' field work together, including step-by-step configuration and troubleshooting guidance. --------- Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com> Co-authored-by: fcoppede <[email protected]>
2026-11-12 17:15:15 +00:00 · 2026-06-24 15:32:38 +00:00
parent 2397247925
commit 9ccafca12b
8 changed files with 41 additions and 10 deletions
@@ -126,7 +126,7 @@ Development mode allows the use of glob patterns in Redirect URIs for flexibilit
 | `[class]`     | Matches any single character against a class of characters (e.g., `[a-z]`). |
 | `{alt1,...}`  | Matches a sequence if one of the comma-separated alternatives matches.      |

-<Callout type="note">
+<Callout type="info">
 Double stars (`**`) should appear surrounded by path separators (e.g., `/**/`). A pattern like `path/to/**.txt` is invalid; use `path/to/**/*.txt`.
 </Callout>

@@ -145,7 +145,7 @@ After creating an application, you can modify its settings.
 * **Auth Method:** You can switch authentication methods (e.g., from Basic to Private Key JWT) via the toggle or dropdowns.
 * **OIDC Compliance:** The Management Console checks if your settings are OIDC compliant and shows tasks for completion if anything is missing.

-<Callout type="caution">
+<Callout type="warn">
 You **cannot** change the Application Type (e.g., from Web to Native) after creation. You must delete and recreate the application.
 </Callout>

@@ -155,6 +155,37 @@ You **cannot** change the Application Type (e.g., from Web to Native) after crea
  width="800px"
 />

+### Use New Login UI
+
+The **Use new login UI** checkbox and **Custom base URL for the new Login UI** field control which login interface your application uses:
+
+* **Checkbox Behavior:** This checkbox only has an effect when the instance-level Login V2 feature flag is **disabled**. When the instance-wide feature is off, checking this box enables Login V2 specifically for this application while other applications continue using Login V1.
+
+* **Custom Base URL:** This field is used when you're running a self-hosted Login UI at a different domain (e.g., `https://login.acme.com`). If you leave this field empty, ZITADEL redirects to its built-in `/ui/v2/login` endpoint.
+
+<Callout type="info">
+If the instance-level Login V2 feature flag is already enabled, all applications use Login V2 by default, and the checkbox has no effect. The feature flag takes precedence over per-application settings.
+</Callout>
+
+**Configuration Steps:**
+
+1. **Per-Application Login V2 (when instance flag is off):**
+   - Check the **Use new login UI** checkbox in your application settings
+   - Optionally enter a custom base URL if using a self-hosted Login UI
+   - This enables Login V2 only for this specific application
+
+2. **Self-Hosted Login UI:**
+   - Deploy your Login UI to a custom domain
+   - Enter the full base URL (e.g., `https://login.acme.com`) in the **Custom base URL** field
+   - Ensure your Login UI is properly configured with the required environment variables and service account permissions
+
+3. **Instance-Wide Login V2:**
+   - Enable the Login V2 feature flag at the instance level (in Default Settings → Features)
+   - When enabled, all applications use Login V2 regardless of individual application settings
+   - The custom base URL field still applies if you want to use a self-hosted Login UI
+
+For detailed setup instructions for self-hosted Login UI, see [Connect your Self-Hosted Login UI to ZITADEL](https://zitadel.com/docs/self-hosting/manage/login-client) and [Hosted Login UI: Authenticate Your Users](https://zitadel.com/docs/guides/integrate/login/hosted-login).
+
 ### Token Settings

 In the **Token Settings** section, you can customize the tokens issued for this application:
@@ -94,7 +94,7 @@ An organization can have multiple domain names, but only one is configured as th
 * Which login name is displayed to the user in the UI.
 * What information is asserted in `access_tokens` (specifically the `preferred_username` claim).

-<Callout type="caution">
+<Callout type="warn">
 Setting an Organization Domain affects users.
 If a user `coyote` exists in the global organization with the login name `[email protected]`, and you subsequently verify `acme.ch` for a specific organization, the global user's login name will be replaced with `coyote@{randomvalue.tld}`. ZITADEL will notify users affected by this change.
 </Callout>
@@ -126,7 +126,7 @@ You can disable domain verification requirements in the [default settings](/guid
 5.  Once verified, click **Verify**.
 6.  (Optional) Click **Set as primary** to make this the default domain for user login names.

-<Callout type="caution">
+<Callout type="warn">
 Do not delete the DNS verification record after success. ZITADEL re-checks domain ownership periodically.
 </Callout>

@@ -40,7 +40,7 @@ Read more about managing roles [here](./roles).
 When creating a new ZITADEL instance, you will find an automatically created project in the first organization.
 This **Default Project** (named "ZITADEL") protects the ZITADEL Management Console and APIs.

-<Callout type="caution">
+<Callout type="warn">
 We do not recommend changing any settings in the Default Project or using it for your own applications, as this could influence the behavior of ZITADEL itself.
 </Callout>