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 Auth0 Management API. To learn how, read Configure ACUL. For the full API schema, review the PATCH /v2/prompts/{prompt}/screen/{screen}/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 UI. You can use partials and 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 style sheet tags. Auth0 uses Subresource Integrity (SRI) to verify that there has been no modification to the assets.

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.

{
  "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. To replace the default Universal Login head tags (such as the favicon) with your own, set default_head_tags_disabled to true.

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 hooks or the 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. Auth0 removes keys that resolve to empty or null values 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

Brand Customization

Code Customization

Third-Party Customization

ACUL Rendering Configuration Reference

Rendering modes

Head tags

Dynamic URL segments

Context data

Brand Customization

Code Customization

Third-Party Customization

Documentation Index

​Rendering modes

​Head tags

​Dynamic URL segments

​Context data

Rendering modes

Head tags

Dynamic URL segments

Context data