auth0 · mswanson · Apr 10, 2026 · Apr 10, 2026
@@ -1242,7 +1242,13 @@
                             "group": "Advanced Customizations for Universal Login",
                             "pages": [
                               "docs/customize/login-pages/advanced-customizations",
-                              "docs/customize/login-pages/advanced-customizations/configure",
+                              {
+                                "group": "Configure ACUL",
+                                "pages": [
+                                  "docs/customize/login-pages/advanced-customizations/configure/overview",
+                                  "docs/customize/login-pages/advanced-customizations/configure/reference"
+                                ]
+                              },
                               "docs/customize/login-pages/advanced-customizations/quickstart",
                               "docs/customize/login-pages/advanced-customizations/development-workflow",
                               "docs/customize/login-pages/advanced-customizations/deployment-workflow",

@@ -70,7 +70,7 @@ We recommend you create a tenant for testing, development, and production with a
 
 | Read... | To learn...                           |
 | -------- | ------------------------------------- |
-| [Configure ACUL](/docs/customize/login-pages/advanced-customizations/configure)  | How to configure ACUL with your Auth0 tenant.                    |
+| [Configure ACUL](/docs/customize/login-pages/advanced-customizations/configure/overview)  | How to configure ACUL with your Auth0 tenant.                    |
 | [ACUL Quickstart](/docs/customize/login-pages/advanced-customizations/quickstart)      | How to get started with an ACUL sample application.    |
 | [ACUL Development Workflow](/docs/customize/login-pages/advanced-customizations/development-workflow)   | About the ACUL development workflow. |
 | [ACUL Deployment Workflow](/docs/customize/login-pages/advanced-customizations/deployment-workflow)   | About the ACUL deployment workflow. |

@@ -1,14 +1,17 @@
 ---
 description: Learn how to configure ACUL
+sidebarTitle: Overview
 title: Configure ACUL
 ---
 
-You can configure ACUL using the Auth0 Dashboard, Management API, and Infrastructure-as-Code(IaC) tools.
+You can configure ACUL using the Auth0 Dashboard, Management API, and Infrastructure-as-Code (IaC) tools. Each method modifies the same per-screen rendering configuration object.
 
 <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
 To configure ACUL, make sure your custom configuration files and assets are hosted on a public CDN. 
 </Callout>
 
+To understand the rendering configuration object and its properties, read [ACUL Rendering Configuration Reference](/docs/customize/login-pages/advanced-customizations/configure/reference).
+
 ## Auth0 Dashboard
 
 You can use the Dashboard to customize your screens with ACUL:
@@ -28,12 +31,6 @@ A. Navigate to [Dashboard > Branding > Universal Login](https://manage.auth0.com
 	</Callout>
 B. Select **Save & Publish**
 
-**Use the ACUL rendering configuration object**
-
-The ACUL rendering configuration is a single JSON object that is used to enable ACUL and list all the available properties, per screen, which consist of specific assets, context data, and applicable conditional logic. The ACUL rendering configuration object can be used with IaC tools and the Auth0 Management API. 
-
-To learn more, review the [`/v2/prompts/patch-rendering`](https://auth0.com/docs/api/management/v2/prompts/patch-rendering) endpoint.
-
 ## Infrastructure-as-Code (IaC)
 
 Configure ACUL with IaC tools, including:
@@ -57,4 +54,3 @@ Use ACUL Management API endpoints to configure Universal Login screens individua
 		* The [`GET /v2/prompts/rendering` endpoint](/docs/api/management/v2/prompts/get-all-rendering) allows you to retrieve configurations for all the screens.
 
 		* The [`PATCH /v2/prompts/rendering` endpoint](/docs/api/management/v2/prompts/patch-bulk-rendering) allows you to update screens in bulk. 
-
@@ -0,0 +1,117 @@
+---
+description: Learn about the ACUL rendering configuration object and its properties
+title: ACUL Rendering Configuration Reference
+---
+
+Each Universal Login screen has its own rendering configuration, a JSON object that controls how Auth0 renders that screen. The rendering configuration defines the rendering mode, the JavaScript and CSS assets that make up your custom UI, and the context data available to your application at runtime.
+
+You can manage the rendering configuration through the Auth0 Dashboard, Infrastructure-as-Code tools, or the Management API. To learn how, read [Configure ACUL](/docs/customize/login-pages/advanced-customizations/configure/overview). For the full API schema, review the [`PATCH /v2/prompts/{prompt}/screen/{screen}/rendering`](/docs/api/management/v2/prompts/patch-rendering) endpoint.
+
+The rendering configuration includes the following properties:
+
+| **Property** | **Type** | **Description** |
+| --- | --- | --- |
+| `rendering_mode` | string | Controls how the screen renders. Accepts `standard` or `advanced`. |
+| `head_tags` | array | An array of HTML elements injected into the page `<head>`. Required when `rendering_mode` is `advanced`; must include at least one `script` tag. |
+| `default_head_tags_disabled` | boolean | When `true`, removes the default Universal Login head tags (such as the favicon). Defaults to `false`. |
+| `context_configuration` | array | A list of context values to send to the browser at runtime. Required when `rendering_mode` is `advanced`. |
+| `use_page_template` | boolean | When `true`, renders the ACUL screen inside the tenant's custom page template, if one is defined. Defaults to `false`. |
+| `filters` | object | Restricts ACUL rendering to specific applications, organizations, or custom domains. When omitted, ACUL applies tenant-wide. |
+
+## Rendering modes
+
+The `rendering_mode` property determines whether a screen uses the default Universal Login UI or your custom ACUL implementation.
+
+* **Standard**: The screen renders using the default [Universal Login](/docs/customize/login-pages/universal-login) UI. You can use [partials](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts) and [template variables](/docs/customize/login-pages/universal-login/customize-templates#page-template-variables) to customize the screen.
+* **Advanced**: The screen renders using your custom JavaScript and CSS assets loaded through `head_tags`. Partials do not apply. By default, advanced mode applies to all applications and organizations on the tenant.
+* **Advanced (filtered)**: The screen renders with ACUL for requests matching the criteria defined in `filters` (specific applications, organizations, or custom domains). Requests that do not match the filters fall back to standard rendering, where partials apply.
+
+To use filtered mode, set `rendering_mode` to `advanced` and provide a `filters` object with a `match_type` (`includes_any` or `excludes_any`) and at least one entity array (`clients`, `organizations`, or `domains`). Each entity can be identified by `id` or by a `metadata` key/value pair.
+
+## Head tags
+
+Head tags are the primary mechanism for loading your custom UI into the ACUL host page. When Auth0 renders a screen in advanced mode, it serves a minimal HTML page and injects the elements defined in `head_tags` into the page `<head>`. These tags load the JavaScript and CSS asset bundles that make up your custom authentication screen.
+
+Each entry in the `head_tags` array is an object with the following properties:
+
+| **Property** | **Type** | **Description** |
+| --- | --- | --- |
+| `tag` | string | The HTML element type. Valid values: `script`, `link`, `style`, `meta`, `title`, `base`, `noscript`, `template`. |
+| `attributes` | object | Attributes for the HTML element (for example, `src`, `href`, `defer`, `integrity`). Maximum of 10 attributes per tag. |
+| `content` | string | Text or markup between the element's opening and closing tags. Maximum of 250 characters. |
+
+The `integrity` attribute is required for `script` and stylesheet tags. Auth0 uses [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) to verify that assets have not been tampered with.
+
+### Dynamic URL segments
+
+Head tag URLs support dynamic segments using Liquid template syntax, which allows you to serve different asset bundles based on the current authentication context. For example, you can load a different JavaScript bundle per client or per organization to support multi-branding.
+
+Available variables for dynamic segments include:
+
+* **Prompt and screen**: `{{ screen.name }}`, `{{ prompt.name }}`, `{{ locale }}`
+* **Client**: `{{ client.id }}`, `{{ client.name }}`, `{{ client.metadata.KEY_NAME }}`
+* **Organization**: `{{ organization.id }}`, `{{ organization.name }}`, `{{ organization.metadata.KEY_NAME }}`
+
+When using dynamic URL segments, provide an SRI hash for each possible asset variant. The `integrity` attribute accepts multiple hashes separated by whitespace; the browser loads the resource if any hash matches.
+
+```json
+{
+  "head_tags": [
+    {
+      "tag": "script",
+      "attributes": {
+        "src": "https://cdn.example.com/assets/{{ client.name }}/bundle.js",
+        "defer": true,
+        "integrity": "sha256-hashForClientA sha256-hashForClientB"
+      }
+    },
+    {
+      "tag": "link",
+      "attributes": {
+        "rel": "stylesheet",
+        "href": "https://cdn.example.com/assets/{{ client.name }}/styles.css",
+        "integrity": "sha256-cssHashForClientA sha256-cssHashForClientB"
+      }
+    }
+  ]
+}
+```
+
+You can also use head tags to load analytics scripts, custom fonts, or meta tags.
+
+Set `default_head_tags_disabled` to `true` if you want to replace the default Universal Login head tags (such as the favicon) with your own.
+
+## Context data
+
+Context data controls which tenant, client, organization, and branding information Auth0 sends to your custom screen at runtime. Auth0 delivers the data through the `universal_login_context` object on the host page. In your application code, use the [ACUL React SDK](/docs/libraries/acul/react-sdk) hooks or the [ACUL JS SDK](/docs/libraries/acul/js-sdk) methods to access context data.
+
+Each value you want available in your screen must be explicitly listed in the `context_configuration` array. Keys that resolve to empty or null values are removed from the payload.
+
+The following static context values are available:
+
+| **Value** | **Description** |
+| --- | --- |
+| `branding.settings` | Tenant branding settings (colors, logo) |
+| `branding.themes.default` | Default Universal Login theme |
+| `client.logo_uri` | Application logo URL |
+| `client.description` | Application description |
+| `organization.display_name` | Organization display name |
+| `organization.branding` | Organization branding settings |
+| `screen.texts` | Localized text strings for the current screen |
+| `tenant.name` | Tenant name |
+| `tenant.friendly_name` | Tenant friendly name |
+| `tenant.logo_url` | Tenant logo URL |
+| `tenant.enabled_locales` | Locales enabled on the tenant |
+| `untrusted_data.submitted_form_data` | Previously submitted form data |
+| `untrusted_data.authorization_params.login_hint` | Login hint from the authorization request |
+| `untrusted_data.authorization_params.screen_hint` | Screen hint from the authorization request |
+| `untrusted_data.authorization_params.ui_locales` | Requested UI locales |
+| `user.organizations` | Organizations the user belongs to |
+| `transaction.custom_domain.domain` | Custom domain for the current transaction |
+
+You can also add dynamic keys using dot notation:
+
+* `client.metadata.YOUR_KEY` for application metadata
+* `organization.metadata.YOUR_KEY` for organization metadata
+* `transaction.custom_domain.domain_metadata.YOUR_KEY` for custom domain metadata
+* `untrusted_data.authorization_params.ext-YOUR_KEY` for custom query parameters passed to the `/authorize` endpoint with the `ext-` prefix
@@ -22,7 +22,7 @@ export interface UserMembers {
 <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
 
 
-* OPT-IN: You must explicitly configure these properties to make them available to the screen. To learn more, read [Configure ACUL](/docs/customize/login-pages/advanced-customizations/configure). 
+* OPT-IN: You must explicitly configure these properties to make them available to the screen. To learn more, read [ACUL Rendering Configuration Reference](/docs/customize/login-pages/advanced-customizations/configure/reference). 
 
 
 * When the Auth0 server is not aware of the current user, the `user` properties are not available in the following screens: