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.

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 or with the Management API.

Prerequisites

• A Portal. To create one, read Universal Portals Quickstart.
• To use the Management API, a Management API access token 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: User MFA Management and Passkey Management.
• Organization components call the My Organization API: Organization Details Edit and Domain Table.
• Form renders an Auth0 Form. Forms work in any Portal to collect or update information.
• 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. To see every component, read Portal Components Library Reference.

Add pages and components

Auth0 Dashboard

1. Open the editor

   Navigate to Auth0 Dashboard > 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.

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:

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.

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 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.

Management API

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

{
  "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.

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.

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.

Management API

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

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 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: 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.

Management API

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\">"
    }
  }'

Auth0 injects custom code only when users open the Portal on a custom domain. 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

Send users from your web or native application to the Portal.

Portal Components Library Reference

Look up component types, configuration limits, and scopes.