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

# Access Portals

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

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

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.

```mermaid theme={null}
flowchart TD
    start("Where does the user start?") --> web["Web application"]
    start --> native["Native application"]
    web --> url["Portal URL"]
    native --> token["Session transfer token"] --> url
    url --> org{"Is an organization<br/>context required?"}
    org -- "Yes" --> param["Include the organization parameter"]
    org -- "No" --> open["Open the portal"]
    param --> open
```

| 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](#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](#open-a-portal-from-a-native-application) |
| [Organization](https://auth0.com/docs/manage-users/organizations.md) context | The Portal manages an Auth0 Organization or users belong to several Organizations | [Open a Portal in an Organization context](#open-a-portal-in-an-organization-context) |

## Prerequisites

* A Portal and its application. To create them, read [Universal Portals Quickstart](https://auth0.com/docs/customize/portals/quickstart.md). To configure the application yourself, read [Configure an Application for Universal Portals](https://auth0.com/docs/customize/portals/configure-portal-application.md).

* The portal URL:

  ```text theme={null}
  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](https://auth0.com/docs/customize/portals/customize-portals.md#set-the-default-page).

* If you want to use Portals with Organizations:
  * The portal application allows Organizations. To learn more, read [Configure an Application for Universal Portals](https://auth0.com/docs/customize/portals/configure-portal-application.md#organization-context).
  * 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](https://auth0.com/docs/manage-users/my-organization-api.md).

## Open a Portal from a web application

Link to the portal URL from your application:

```html wrap lines theme={null}
<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 (Single Sign-On (SSO): Service that, after a user logs into one application, automatically logs them into other applications as well. Single Logout works similarly in reverse.) 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](https://auth0.com/docs/authenticate/single-sign-on/native-to-web) 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](https://auth0.com/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web.md). Then configure the portal application to accept session transfer tokens. To learn more, read [Configure an Application for Universal Portals](https://auth0.com/docs/customize/portals/configure-portal-application.md#native-application).

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

```bash wrap lines theme={null}
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:

```text theme={null}
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:

```text theme={null}
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](https://auth0.com/docs/manage-users/organizations.md). Always include it for business Portals, because the [My Organization API](https://auth0.com/docs/manage-users/my-organization-api.md) 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:

```text theme={null}
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](https://auth0.com/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api.md).

### 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](#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](https://auth0.com/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web.md#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](https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication.md) keeps the user in the same Organization.

## Run an Action when users open a Portal

A Portal sign-in runs your [post-login Actions](https://auth0.com/docs/customize/actions/actions-overview.md). 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:

```javascript wrap lines theme={null}
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](https://auth0.com/docs/customize/forms.md) 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:

```javascript wrap lines theme={null}
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](https://auth0.com/docs/customize/forms/render.md).

## 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](https://auth0.com/docs/customize/portals/configure-portal-application.md)**
>
> Set the application options that Native Applications and Organizations need.

> **[Universal Portals Architecture](https://auth0.com/docs/customize/portals/architecture.md)**
>
> See how sign-in, component calls, and sessions work inside a Portal.

> **[Troubleshoot Universal Portals](https://auth0.com/docs/customize/portals/troubleshoot-portals.md)**
>
> Fix sign-in and Organization problems.