Skip to main content

Enable public access to a Retool app

Learn about options for sharing and embedding apps with or without user authentication.

You can share Retool apps directly with users and embed them into web apps using iframes. If your apps don't need user authentication, you can create Public apps and embed them into your parent application using a public link.

If you need authentication and don't want users to log in through the Retool login screen, you can integrate Retool with an Identity Provider on self-hosted Retool, or use Retool Embed. See the User authentication in embedded apps section to learn more.

note

Retool Embed lets you authenticate users into embedded Retool apps using an API. Because authentication is API driven, after users log into your parent application, you can let them seamlessly access Retool apps without having to go through the Retool login flow.

Embed apps with JavaScript​

You can embed apps using Retool's JavaScript SDK. After including the JavaScript SDK library, you initialize an instance of your Retool app and embed it at the specified location using window.retool.RetoolDashboard().

<html>
  <head>
    <script src="https://cdn.tryretool.com/embed.js"> </script>
  </head>
  <body>
    <div style="height: 800px; width: 100%;" id="container"></div>
    <script>
      var rt =
      window.retool.RetoolDashboard(document.getElementById('container'),
      'https://retool.yoursite.com/apps/embedded-app')
    </script>
  </body>
</html>

Embed apps with React​

To embed apps with React, install the react-retool npm module and then import it into your project.

// with npm
$ npm install react-retool  --save

// with yarn
$ yarn add react-retool

See the React wrapper documentation for more information.

If you need to embed a Retool app into another web app, your code might look something like this.

import React from "react";
import Retool from "react-retool";

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = { value: 0 };
  }

  buttonClicked(event) {
    this.setState({ value: this.state.value + 1 });
  }

  render() {
    return (
      <div className="App">
        <div className="parent-react-app-container">
          <h1>I am a react app</h1>
          <h2>
            Value Retool will read on load:
            <span id="id-value-retool-reads">hello</span>
          </h2>
          <div>
            <h2>
              <span id="other-id-value-retool-reads">{this.state.value}</span>
            </h2>
            <button onClick={this.buttonClicked}>
              Increment Dynamic Value
            </button>
          </div>
        </div>

        <div className="retool-box">
          <Retool url="https://retool.yoursite.com/apps/embedded-app" />
        </div>
      </div>
    );
  }
}

export default App;

Pass data between embedded and parent apps​

Embedded Retool apps can use Parent Window Queries to read values from the parent application. They can also use JavaScript queries to pass data back to the parent app using the browser's postMessage API.

Pass data to an embedded app​

You can read data from parent apps with Parent Window Queries. If you embed your app with JavaScript, pass the CSS selector for the value to read. With React, pass the key in the data prop that you want to read.

Pass data to the parent app​

To pass data to the parent app, create a JavaScript query and use the postMessage API to send the data. For example, a query that sends the email address of the current_user to the parent app might look like this.

Posting a message to the parent application.

On the parent application side, the code to listen to and handle these messages might look like this.

window.addEventListener(
  "message",
  function (e) {
    console.log("Parent window received: ", e.data);
  },
  false,
);

The code to handle postMessage requests depends on your specific implementation. You might need to write something more complex than the above example.

User authentication in embedded apps​

Because building functionality in Retool is often faster than through writing code, it's common to embed Retool apps into existing portals, tools, and applications.

The following sections explain how to provide a seamless and secure experience to end users, without requiring a double-login (logging into the parent application, and separately into the embedded Retool app).

MethodAuthentication supportShows Retool login screenIdP requiredPlan availability
Direct link (Retool App)YesYesNoAll plans
Direct link (Public App)NoNoNoBusiness and above
Direct link (with IdP integration)YesNoYesEnterprise
Retool EmbedYesNoNoBusiness and above
Per-user authentication not available publicly

Resources that support per-user authentication (e.g., Google Sheets and OAuth) prevent apps from being shared publicly.

Retool Embed​

Retool Embed is the recommended approach for authenticating end users into embedded Retool apps. You can use your existing authentication flow to generate a one-time URL that you can then use within an iframe.

User authentication with an Identity Provider​

If you have SAML or OIDC SSO set up on your self-hosted Retool instance, you can also authenticate end users into embedded Retool apps. As long as your existing web application uses the same SSO Identity Provider (IdP) as Retool, you can share the user's authentication state between the parent and embedded apps.

warning

Your IdP must allow iframe embedding to authenticate end users into embedded Retool apps.

Prevent double logins​

If you configure your web application and Retool to use the same IdP, a user who signs into the web application may still have to sign in again to access the embedded Retool app. You can configure Retool to automatically sign in the user with SSO instead of using a login screen. This takes effect whenever a user has an existing, authenticated session on the IdP.

To configure this, navigate to your organization's Single Sign-On settings and enable Trigger Login Automatically. Self-hosted organizations can also configure this by setting one of the following environment variables to true in the docker.env file.

  • TRIGGER_SAML_LOGIN_AUTOMATICALLY if using SAML.
  • TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY if using OIDC SSO.

Public apps​

note

Public apps are only available on Retool Cloud with Business and Enterprise plans.

You can share Retool apps publicly with a Public access link. You can share this link directly with users or embed the app in an iframe in other applications or web pages. These apps can be accessed by anyone on the internet and always reflect the production environment of the app.

To create a Public access link, open an app in the App IDE and click the Share button in the top right. Select the Public tab and click Enable public link.

Password-protected public apps are changing

On February 18th, 2024, Retool plans to end support for creating password-protected Public Apps. If need to build authenticated external apps, check out our guide. Should you have further questions, please get in touch.

Enabling a public access link