Universal Portals Architecture

A Portal is a server-side application that Auth0 hosts. The portal server signs users in, keeps their tokens, and calls resource servers for them. The browser never sees an access token or a refresh token. It holds only a secure session cookie. The following sections explain the actors in a Portal, how users sign in, how components call resource servers, and how step-up authentication, Forms, and sessions work. To create your first Portal, read Universal Portals Quickstart. To open a Portal from your application, read Access Portals. To configure the portal application, read Configure an Application for Universal Portals.

Actors

Browser: Shows the Portal and the components.
Portal server: Signs users in, stores tokens, and proxies component calls to the resource servers.
Auth0: The authorization server that signs users in and issues tokens.
My Account API and My Organization API: The resource servers that components call.
Forms backend: Runs Auth0 Forms and their Flows.

Access with single sign-on

When a user opens the portal URL, the portal server starts an authorization code flow with Proof Key for Code Exchange (PKCE). If the user has an Auth0 session, Auth0 returns an authorization code without a login prompt. The portal server exchanges the code for an ID token, an access token, and a refresh token, and stores them. It then sets the session cookie. If the user has no Auth0 session, Auth0 shows the login page before it returns the code.

Access with a session transfer token

A native application can pass a session transfer token in the portal URL. The portal server forwards the token to /authorize. Auth0 validates the token, signs the user in without a prompt, and returns the code, as in . A session transfer token works once and expires after 60 seconds. If Auth0 rejects the token, the user sees the login page. To implement this scenario, read Open a Portal from a native application.

Component calls to a resource server

A component never calls a resource server from the browser. It sends the request to the portal server at /portals/{slug}/proxy/..., with the audience and scope it needs. The portal server adds an access token and forwards the request to the API.

Access token minting

Portals always require a . The portal server uses it as the main mechanism to mint access tokens for each resource server that your components call. It relies on a multi-resource refresh token (MRRT) to pivot between audiences, so the user signs in once. The Portal reuses an access token until it expires, and then mints a new one. The portal application needs two settings for each resource server: a client grant that allows the scopes, and a refresh token policy that allows the exchange. To learn more, read Multi-Resource Refresh Token.

Allowed resource servers

Component calls go only to the My Account API and the My Organization API of your tenant, and only to the ones that the portal application has a client grant for. The recommended configuration grants both. The portal server rejects a request for any other audience with 403.

Rate limits

If the My Account API returns 429 Too Many Requests while a multi-factor authentication (MFA) or passkey component loads data, the Portal replaces the component with a “Too many requests” message and a retry button.

Step-up authentication

Whether an operation requires MFA depends on your tenant’s policies and Actions. For example, imagine that your tenant has this post-login Action. It requests an MFA challenge when a refresh token exchange asks for the My Account API with the scope to delete an authentication method. The request hostname gives the domain, so the Action works with your Auth0 domain or a custom domain:

exports.onExecutePostLogin = async (event, api) => {
    const { protocol } = event.transaction ?? {};
    const { hostname, body } = event.request ?? {};

    const isRefreshTokenExchange = protocol === "oauth2-refresh-token";
    const isMyAccountApi = body?.audience === `https://${hostname}/me/`;
    const deletesAuthenticator = body?.scope?.includes("delete:me:authentication_methods");

    if (isRefreshTokenExchange && isMyAccountApi && deletesAuthenticator) {
        api.authentication.challengeWithAny([{ type: "email" }, { type: "otp" }]);
    }
};

When the Portal requests an access token for that audience and scope, Auth0 runs the Action, which asks the user to choose a factor, and responds with mfa_required. The Portal starts the MFA challenge in a popup and retries the original request after the user completes it. To learn more, read Action Triggers: post-login - API object.

Forms submission

An Auth0 Form renders inside the portal page, but its requests go from the browser to the Forms backend, not through the portal server. The Forms backend runs the Flow. If the Flow calls an API, it uses credentials from a Forms vault connection. The API is a resource server, typically the Management API, but it can be any API. The Form receives its context from the user’s ID token when the Portal loads. To learn more, read Forms context variables.

Sessions and token lifetimes

A Portal has two sessions and two kinds of tokens:

Auth0 session: Set by Auth0 when the user signs in. Your tenant’s session settings control it.
Portal session: The Portal’s session cookie. It ends after 1 hour of inactivity or 1 day after sign-in, whichever comes first.
Refresh token: The portal server’s credential for minting access tokens. Every API call depends on it, so set its lifetimes to match the portal session.
Access token: Minted when a component needs it and reused until it expires. Set its lifetime on the resource server according to your security policy.

When the portal session ends, the Portal redirects the user to Auth0 to sign in again. If the refresh token expires before the portal session, API calls fail until the user signs in again. To avoid this, use the lifetimes in Configure an Application for Universal Portals.

Next steps

Universal Portals Quickstart

Create your first Portal in minutes.

Configure an Application for Universal Portals

Set the client grants and refresh token policies that access token minting needs.

Access Portals

Send users from your applications to the Portal.

Troubleshoot Universal Portals

Fix sign-in, session, and API errors.

Brand Customization

Code Customization

Third-Party Customization

Universal Portals Architecture

Actors

Access with single sign-on

Access with a session transfer token

Component calls to a resource server

Access token minting

Allowed resource servers

Rate limits

Step-up authentication

Forms submission

Sessions and token lifetimes

Next steps

Universal Portals Quickstart

Configure an Application for Universal Portals

Access Portals

Troubleshoot Universal Portals

​Actors

​Access with single sign-on

​Access with a session transfer token

​Component calls to a resource server

​Access token minting

​Allowed resource servers

​Rate limits

​Step-up authentication

​Forms submission

​Sessions and token lifetimes

​Next steps

Universal Portals Quickstart

Configure an Application for Universal Portals

Access Portals

Troubleshoot Universal Portals

Actors

Access with single sign-on

Access with a session transfer token

Component calls to a resource server

Access token minting

Allowed resource servers

Rate limits

Step-up authentication

Forms submission

Sessions and token lifetimes

Next steps