Access Portals

Send users to a Universal Portal from a web application, from a native application, or in the context of an organization.

Every Auth0 Universal Portal has a URL, so users already signed in to your application can open the Portal without a login prompt.

Portals provides several options as an entry point. Select the entry point that matches your user experience.

Entry point	Use it when	Section
Web Application	Users start in a Web Application that uses the same Auth0 domain	Open a Portal from a web application
Native Application	Users start in a Native Application and the Portal opens in an in-app browser	Open a Portal from a native application
Organization context	The Portal manages an Auth0 Organization or users belong to several Organizations	Open a Portal in an Organization context

Prerequisites

• A Portal and its application. To create them, read Universal Portals Quickstart. To configure the application yourself, read Configure an Application for Universal Portals.

• The portal URL:

  https://YOUR_DOMAIN/portals/{slug}
  

  YOUR_DOMAIN is your custom domain, or your Auth0 domain if you don’t have a custom domain. {slug} is the portal slug.

  The URL opens the Portal’s default page. If the Portal has no default page, users are presented with a “Page not found” error message. To configure a default page, read Configure Universal Portals.

• If you want to use Portals with Organizations:

  • The portal application allows Organizations. To learn more, read Configure an Application for Universal Portals.
  • The user is a member of the Organization.
  • For a business Portal, the user has the Organization permissions that the components need. To learn more, read My Organization API.

Open a Portal from a web application

Link to the portal URL from your application:

<a href="https://YOUR_DOMAIN/portals/{slug}">Manage your account</a>

When the user has an Auth0 session on the same domain as the Portal, Auth0 signs them in to the Portal with single sign-on and no login prompt. When the user has no session, Auth0 shows the login page, and then returns the user to the Portal.

Open a Portal from a native application

Native to Web SSO transfers the user’s session from your Native Application to the Portal. The Native Application exchanges its refresh token for a single-use session transfer token, and then opens the Portal in an in-app browser with that token in the URL.

Before you start, configure Native to Web SSO on your Native Application. To learn more, read Configure and Implement Native to Web SSO. Then configure the portal application to accept session transfer tokens. To learn more, read Configure an Application for Universal Portals.

Exchange the refresh token for a session transfer token

Make this request immediately before you open the in-app browser. The token expires after 60 seconds and works once.

curl --request POST \
  --url "https://YOUR_DOMAIN/oauth/token" \
  --header "content-type: application/json" \
  --data '{
    "grant_type": "refresh_token",
    "client_id": "{nativeClientId}",
    "refresh_token": "{refreshToken}",
    "audience": "urn:YOUR_DOMAIN:session_transfer"
  }'

The access_token in the response is the session transfer token.

Open the in-app browser

Open the portal URL with the token:

https://YOUR_DOMAIN/portals/{slug}?session_transfer_token={sessionTransferToken}

The Portal forwards the token to Auth0 and signs the user in.

Hide portal navigation for in-app browsers

By default, a Portal shows a top bar, a sidebar, and a user menu. In an in-app browser, your Native Application already provides navigation and user context, so you can hide these elements with URL parameters:

Parameter	Effect
hide_sidebar=true	Removes the sidebar navigation and its user menu.
hide_topbar=true	Removes the top bar.
hide_user_menu=true	Removes the user avatar and menu from the top bar and the sidebar.

The following wireframes show the result of each parameter and of common combinations:

The parameters persist while the user navigates between portal pages, so you add them once, when you open the in-app browser:

https://YOUR_DOMAIN/portals/{slug}?session_transfer_token={sessionTransferToken}&hide_sidebar=true&hide_user_menu=true

Open a Portal in an Organization context

Use the organization parameter to open a Portal for a specific Organization. Always include it for business Portals, because the My Organization API needs an Organization to act on. Include it for consumer Portals when users belong to several Organizations.

Build the URL

Add the Organization to the portal URL:

https://YOUR_DOMAIN/portals/{slug}?organization={organization}

The Portal forwards organization to the Auth0 /authorize endpoint, so use the same identifier format as your other /authorize requests: the Organization ID, such as org_abc123, or the Organization name when your tenant is set up to accept names. To learn more, read Use Organization Names in Authentication API.

Open the Portal from your application

Choose the Organization in your application, and then link to the URL. In a Native Application, add organization to the URL that you open in the in-app browser. To learn more, read Open a Portal from a native application.

For a Native Application, the organization value must match the Organization of the session transfer token. If they differ, Auth0 rejects the token and the user signs in again. To learn more, read Native to Web SSO with Organizations.

Switch Organizations

When a user with an active portal session opens the Portal with a different organization, the Portal signs the user in again for that Organization and replaces the previous portal session.

What the Portal does in an Organization context

• Components that call the My Organization API act on the user’s Organization.
• The Portal applies that Organization’s branding.
• An MFA step-up challenge keeps the user in the same Organization.

Run an Action when users open a Portal

A Portal sign-in runs your post-login Actions. To run logic only for the Portal, compare the application’s Client ID with event.client.client_id.

The following example restricts access to a business Portal and assumes you assign an admin role to your Organization administrators. Only users signed in with an Organization and with the admin role should be able to access the Portal:

exports.onExecutePostLogin = async (event, api) => {
  const PORTAL_CLIENT_ID = "{portalClientId}";

  if (event.client.client_id !== PORTAL_CLIENT_ID) {
    return;
  }

  const roles = event.authorization?.roles ?? [];

  if (!event.organization || !roles.includes("admin")) {
    api.access.deny("Only organization administrators can open this portal.");
  }
};

You can also render an Auth0 Form that asks users to accept your terms before they open the Portal. The Form’s Flow can record the acceptance, so the Action does not render the Form again:

exports.onExecutePostLogin = async (event, api) => {
  const PORTAL_CLIENT_ID = "{portalClientId}";

  if (event.client.client_id !== PORTAL_CLIENT_ID) {
    return;
  }

  if (!event.user.app_metadata?.terms_accepted) {
    api.prompt.render("{formId}");
  }
};

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after the user completes the form
};

To learn more, read Render Forms using Actions.

URL parameters

Parameter	Value	Forwarded to /authorize	Description
session_transfer_token	String	Yes	Session transfer token for Native to Web SSO. Single use, expires after 60 seconds.
organization	String	Yes	Organization ID or name to sign the user in with.
hide_sidebar	true	No	Removes the sidebar.
hide_topbar	true	No	Removes the top bar.
hide_user_menu	true	No	Removes the user menu from the top bar and the sidebar.

Next steps

Configure an Application for Universal Portals

Set the application options that Native Applications and Organizations need.

Universal Portals Architecture

See how sign-in, component calls, and sessions work inside a Portal.

Troubleshoot Universal Portals

Fix sign-in and Organization problems.