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-10-18 05:52:51 +00:00 · 2026-06-24 15:32:38 +00:00
parent 2397247925
commit 9ccafca12b
8 changed files with 41 additions and 10 deletions
@@ -6,7 +6,7 @@ sidebar_label: Migrate from V1 to V2

 This guide helps existing users understand the shift from Actions V1 (Embedded) to V2 (Webhook), and provides guidance for new users on how to work with Actions V2.

-<Callout type="caution">
+<Callout type="warn">
 Deprecation Notice
 Actions V1 APIs are planned to be sunsetted in ZITADEL V5. While a definitive V5 release date is not yet available, this is the final timeline for V1 API removal. Actions V1 will receive no new features, and all new implementations must use V2.
 </Callout>
@@ -20,7 +20,7 @@ You have to spin up your own local ZITADEL.
 The easiest way to do so is [by following the Docker Compose installation guide](/self-hosting/deploy/compose).
 </Callout>

-<Callout type="caution">
+<Callout type="warn">
 Beware that these example settings neither supports LDAPS nor StartTLS.
 We highly recommend to enable LDAPS or StartTLS in your production setup.
 Otherwise, your users passwords are sent in clear text through the wire.
@@ -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>

@@ -14,7 +14,7 @@ Caching is an experimental beta feature. See the [Caches](/self-hosting/manage/c

 Zitadel supports Redis or any Redis-compatible store (for example, Valkey) in standalone mode. Sentinel and Redis Cluster are not supported because the cache connector expects a single endpoint and does not implement cluster routing or sentinel failover logic.

-<Callout type="note">
+<Callout type="info">
 Zitadel supports server-auth TLS (`rediss://` scheme) but does not support client certificates/mTLS for cache connections.
 </Callout>

@@ -86,7 +86,7 @@ ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:<strong-password>@<your-host>

 **Run setup and start**

-<Callout type="note">
+<Callout type="info">
 For production deployments, configure TLS to encrypt authentication traffic. See the [TLS configuration guide](/self-hosting/manage/tls_modes) for the available modes.
 </Callout>

@@ -65,7 +65,7 @@ when you install ZITADEL from scratch.
 **Schema bootstrapping step** (requires database owner privileges, uses the service user):
 - If they don’t exist already, it creates all schemas (`eventstore`, `projections`, `system`) and base tables.

-<Callout type="note">
+<Callout type="info">
 **Manual provisioning:** If you handle the provisioning step yourself (e.g. on a managed PostgreSQL service where you don’t have superuser access),
 you can skip it entirely by running only the schema bootstrapping step: