Skip to main content
Applies to: Self-hosted 3.253 Stable

Build custom pages

Learn how to build custom pages in Retool.

Organization admins can replace Retool’s login, reset password, signup, and invitation claim pages with Retool apps. This allows you to customize the entire user journey, which is valuable if you white-label Retool for external users outside your organization.

This guide covers how to set Retool applications as your custom pages and use user actions to control the user lifecycle (login, reset password, claiming an invite, etc.).

Configurable custom pages​

You can replace the following pages with Retool apps:

  • Log in
  • Confirm reset password
  • Claim invitation
  • 403 Error page
  • 404 Error page

Each of these pages has a distinct route necessary for the user flow to work. For example, from an invite email, Retool needs to know which URL to open (e.g., that of a Retool-managed page or Retool app). Other flows, like how users input their passwords, or sign up for Retool, can be entirely defined by you.

Generate custom pages​

You can use either an existing app or a new app to use as a custom page. Retool recommends creating a new page through the following flow, because it generates template apps that are preconfigured with UI elements and the necessary user actions.

Branding preview
  1. Go to Settings > Branding.
  2. From the Preview section, confirm the dropdown is set to the page you want to modify, such as Log in.
  3. Click Manage.
  4. Select Create a new app.
  5. Set a custom URL for your app. Retool automaticallys generate the public link at [your_domain].com/p/[custom_url].
  6. Navigate to the Apps page, and locate your app.

New apps created from this flow are placed in the root folder (found under Published on the Apps landing page). Ensure you restrict access to these apps by moving them to a more privileged folder, such as the External apps folder.

Customize custom pages​

This section covers how to build custom custom pages using Retool apps.

Because these apps deal with sensitive information, restrict their access to admins and developers with only the most privileged access.

The template apps generated from Branding settings work with no additional configuration. Password reset and invite links automatically use the public, custom URL set.

These template apps also come prebuilt with user actions. User actions are an easy-to-use wrapper on top of Retool’s public APIs for:

  • Logging in
  • Logging out
  • Claiming invites
  • Sending password reset links
  • Confirming reset passwords

User actions are used the same as any other Retool query, except that they can only be called from within apps.

Build your login page​

The login page serves as the default landing page for unauthenticated users. When users log out of Retool, they are automatically redirected to this page, though you can still access the Retool-managed login page at [your_domain].retool.com/auth/login. You can use this single page with user actions to support login, password reset, and signup.

When building your login page, use the Login user action.

Build queries for login user actions

The Login user action supports the following login methods:

  • Email and password
  • Google SSO
  • SAML SSO, when already configured in Settings > SSO
  • OIDC SSO, when already configured in Settings > SSO

To ensure users are routed to the Retool home page or a workspace, add an event handler. When you specify / as the path, Retool routes the user to the home page, or if they have a workspace set for their permission group, to their workspace app.

Build password reset and invite flows​

You can use the Send reset password email user action to support password reset flows. You can use these actions within your same login app, e.g., by adding a new view to your container, or by creating a dedicated page for password resets and linking to it from your login page.

The Send reset password email user action automatically validates the password reset token and email address passed as URL parameters. You can similarly build additional apps and functionality for claiming invites and confirming password resets using the Claim invitation and Confirm password reset flows.

Build a signup flow​

You can use the Retool API to build a self-service signup flow for your users.

Build a signup flow for your users

In the example login page above, when a user completes the onboarding questionnaire, the form triggers a query calling POST /user_invites with the form inputs in the metadata field, as well as the default permission groups.

When the user is created upon claiming the invitation, the companyName value will be stored on the user object. As an editor, you can access this value by referencing {{ current_user.metadata.companyName }}.

Assign custom pages​

For each custom page you created, ensure that each app has a public link. Then, return to the Settings > Branding page, and complete the following steps:

  1. From the Preview section, confirm the dropdown is set to the page you want to modify, e.g., Login.
  2. Select Manage.
  3. Select the app that you want to use as the custom page.

Security​

Because these apps touch the core user lifecycle, it's important to build these applications with security best practices in mind. User actions do not make Retool any less secure, since these endpoints do not require authentication and are publicly accessible—anyone can attempt to reset the password for any email address.

Retool relies on the security of the reset password and invitation process, meaning the links are only accessible from the user’s or admin's email inbox.