> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Universal Portals

> Add pages, components, Auth0 Forms, navigation, branding, and custom code to a Universal Portal in the Auth0 Dashboard or with the Management API.

> [!WARNING]
>
> **The Auth0 Universal Portals feature is in .**

A Portal consists of navigation and pages. Navigation is a sidebar of links. Each page is composed of components, such as a heading, an MFA management component, or an Auth0 Form. A section is also a component, and it holds other components.

You can edit your Portal in the visual editor in the [Auth0 Dashboard](https://manage.auth0.com/dashboard/#/universal-portals) or with the [Management API](https://auth0.com/docs/api/management/v2.md).

Wireframe of an end-user portal. The top bar and the sidebar are the navigation. The page next to the sidebar holds components. One component holds two other components.

## Prerequisites

* A Portal. To create one, read [Universal Portals Quickstart](https://auth0.com/docs/customize/portals/quickstart.md).
* To use the Management API, a [Management API access token](https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens.md) with the `read:portals` and `update:portals` scopes.

## Choose components

A Portal can use any mix of components, so you can build a personal account Portal, an Organization Portal, or both. Components fall into four groups:

* **Account components** call the [My Account API](https://auth0.com/docs/manage-users/my-account-api.md): [User MFA Management](https://auth0.com/docs/customize/portals/portal-components.md#user-mfa-management) and [Passkey Management](https://auth0.com/docs/customize/portals/portal-components.md#passkey-management).
* **Organization components** call the [My Organization API](https://auth0.com/docs/manage-users/my-organization-api.md): [Organization Details Edit](https://auth0.com/docs/customize/portals/portal-components.md#organization-details-edit) and [Domain Table](https://auth0.com/docs/customize/portals/portal-components.md#domain-table).
* **Form** renders an [Auth0 Form](https://auth0.com/docs/customize/forms.md). Forms work in any Portal to collect or update information.
* **[Content and structure components](https://auth0.com/docs/customize/portals/portal-components.md#content-and-structure-components)** arrange the page: Heading, Rich Text, Image, and Section.

Account and Organization components call a resource server on the user's behalf, so the portal application needs access to it. To learn more, read [Configure an Application for Universal Portals](https://auth0.com/docs/customize/portals/configure-portal-application.md). To see every component, read [Portal Components Library Reference](https://auth0.com/docs/customize/portals/portal-components.md).

## Add pages and components

**Auth0 Dashboard**

**1. Open the editor**

Navigate to [**Auth0 Dashboard > Portals**](https://manage.auth0.com/dashboard/#/universal-portals) and open your Portal.

**2. Add a page**

Open **Pages**, select **Add Page**, and enter a **Name** and a **Slug**. The slug uses lowercase letters, numbers, and hyphens, and starts with a letter.

**3. Add components**

Open **Components** and drag a component onto the page, or select **Section** first and add components inside it. A section shows a title and a description above its components.

**4. Change a component**

Select a component on the page to open its settings, and then select **Save**.

The visual editor with the Components panel open. The Form component is dragged from the panel and dropped onto the page, where it appears in a new block.

**Management API**

Call `PATCH /api/v2/portals/{id}` with the complete `pages` value. The API replaces the whole `pages` field, so send every page you want to keep. The following example creates a Security page with two sections:

```bash wrap lines theme={null}
curl --request PATCH \
  --url "https://YOUR_DOMAIN/api/v2/portals/{portalId}" \
  --header "authorization: Bearer {managementApiToken}" \
  --header "content-type: application/json" \
  --data '{
    "pages": {
      "default": "security",
      "standard": [
        {
          "title": "Security",
          "slug": "security",
          "components": [
            {
              "type": "page:component:auth0:structure:section",
              "config": {
                "variant": "card",
                "title": "Multi-factor authentication",
                "description": "Add or remove the ways you verify your sign-in.",
                "children": [
                  { "type": "page:component:auth0:my_account:mfa_management" }
                ]
              }
            },
            {
              "type": "page:component:auth0:structure:section",
              "config": {
                "variant": "card",
                "title": "Passkeys",
                "description": "Sign in without a password.",
                "children": [
                  { "type": "page:component:auth0:my_account:passkey_management" }
                ]
              }
            }
          ]
        }
      ]
    }
  }'
```

Send `"pages": null` to remove all pages. Omit `pages` to leave them unchanged.

## Set the default page

The portal URL, `https://YOUR_DOMAIN/portals/{slug}`, opens the Portal's default page. If the Portal has no default page, the URL shows "Page not found".

**Auth0 Dashboard**

Navigate to **Pages**. Open the menu of the page that users should see first, and select **Set as default page**. The page shows a **Home page** label.

The visual editor with the Pages panel open. The three-dot menu of a page opens and shows the Set as default page and Delete options. After Set as default page is selected, the home icon moves to that page.

**Management API**

Set `pages.default` to the slug of one of your pages, as in the previous example.

## Add an Auth0 Form

Create an [Auth0 Form](https://auth0.com/docs/customize/forms.md) to use with Universal Portals. Use the Form to collect information, such as a profile update or communication preferences.

**Auth0 Dashboard**

**1. Add the Form component**

Open **Components** and drag **Form** into a section on your page.

**2. Set the Form**

Select the component. In **Form ID**, enter the ID of your Form. In **Completion message**, enter the message that appears after the user submits the Form. Select **Save**.

The visual editor with a Form component selected inside a section. The Form panel on the right has the Form ID and Completion message fields, a save button at the bottom left, and a delete icon at the bottom right.

**Management API**

Add a `page:component:auth0:form` component to a page. The following example places it in a section:

```json wrap lines theme={null}
{
  "type": "page:component:auth0:structure:section",
  "config": {
    "variant": "card",
    "title": "Personal information",
    "description": "Update the details we have about you.",
    "children": [
      {
        "type": "page:component:auth0:form",
        "config": {
          "form_id": "{formId}",
          "completion_message": "Your profile has been updated."
        }
      }
    ]
  }
}
```

A Form in a Portal receives its context from the user's ID token, not from a login transaction. Only `{{context.user.user_id}}` is always available. To learn more, read [Forms context variables](https://auth0.com/docs/customize/portals/portal-components.md#forms-context-variables).

If a Form sends identifiers to the browser for the user to select, such as a list of MFA factors, and your Flow then uses the selected value, verify in the Flow that the value belongs to the signed-in user. Compare it with `{{context.*}}` or with a list you fetch in a Flow action and store in `{{vars.*}}`.

If a Form updates users through the Management API, its Flow needs a Forms vault connection. Back the connection with a separate machine-to-machine application. Do not add the `client_credentials` grant to the portal application. To learn more, read [Auth0 Vault Connections](https://auth0.com/docs/customize/forms/vaults/auth0.md).

## Arrange content

Group related components in a **Section**. A section shows a title and a description above its components, like a card, which makes a page easier to scan. Use **Heading** and **Rich Text** for text, and **Image** for brand assets such as a logo.

## Configure navigation

The sidebar shows links to portal pages or to external URLs.

**Auth0 Dashboard**

**1. Add an item**

Open **Navigation**, select **Add Item**, and choose a link to a portal page or to an external URL.

**2. Set the link**

Enter a label, choose the page or enter the URL, and optionally enter an icon name. Select **Add Item**.

**3. Reorder the items**

Drag items to change their order.

The visual editor with the Navigation panel open. The panel has an Add Item button above the sidebar items. The Profile and Security items swap places in the panel and in the portal preview, which shows that the order of the panel is the order of the sidebar.

**Management API**

Set the Portal's `navigation` property. As with pages, send the complete value.

```bash wrap lines theme={null}
curl --request PATCH \
  --url "https://YOUR_DOMAIN/api/v2/portals/{portalId}" \
  --header "authorization: Bearer {managementApiToken}" \
  --header "content-type: application/json" \
  --data '{
    "navigation": {
      "sidebar": {
        "components": [
          {
            "type": "sidebar:component:auth0:internal_link:v2",
            "config": { "label": "Security", "page_slug": "security", "icon": "shield" }
          },
          {
            "type": "sidebar:component:auth0:external_link:v2",
            "config": { "label": "Help center", "href": "https://example.com/help" }
          }
        ]
      }
    }
  }'
```

The icon is the name of a [Lucide icon](https://lucide.dev/icons) in kebab-case, such as `user` or `shield`. The sidebar logo comes from your tenant's branding.

## Apply branding

Portals use your tenant's [branding](https://auth0.com/docs/customize/login-pages/universal-login/customize-themes.md): logo, colors, and fonts. In an Organization context, the Portal uses that Organization's branding. If Auth0 cannot load the Organization's branding, the Portal uses your tenant's branding.

## Add custom code to the head

Add HTML to the `<head>` of every portal page, for example to load a font or an analytics script.

**Auth0 Dashboard**

Open **Portal Settings**, and enter your HTML in **Custom HTML injection in \<head>** under **Custom code**.

The visual editor with the Portal Settings panel open. The panel has general, application, and custom code sections, and the custom code section has a code editor.

**Management API**

```bash wrap lines theme={null}
curl --request PATCH \
  --url "https://YOUR_DOMAIN/api/v2/portals/{portalId}" \
  --header "authorization: Bearer {managementApiToken}" \
  --header "content-type: application/json" \
  --data '{
    "custom_code": {
      "head": "<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">"
    }
  }'
```

> [!WARNING]
>
> Auth0 injects custom code only when users open the Portal on a [custom domain](https://auth0.com/docs/customize/custom-domains.md). The code can be up to 10,000 characters. Auth0 does not validate it. You are responsible for its security and its effect on performance.

## Publish and preview

In the visual editor, the top bar shows **Unpublished changes** until you select **Publish**. **Preview** opens the last published version of your Portal in a new tab, so publish before you preview.

## Next steps

> **[Access Portals](https://auth0.com/docs/customize/portals/access-portals.md)**
>
> Send users from your web or native application to the Portal.

> **[Portal Components Library Reference](https://auth0.com/docs/customize/portals/portal-components.md)**
>
> Look up component types, configuration limits, and scopes.