Share Retool apps

Learn how to share or embed apps to allow access without logging into Retool.

You can share Retool apps by embedding them in iframes or enabling public links. You can also add authentication to embedded apps if Retool is integrated with the same Identity Provider as the parent application. Adding authentication requires that you self-host Retool.

📘

Retool Embed

Retool Embed is a new beta feature for allowing external users––partners, vendors, customers––to securely access embedded Retool apps within your product. You can use any authentication solution to give users access, and then control app behavior, data access, and audit usage on a per-user basis. See the Retool Embed documentation if you're interested in joining the beta.

If your apps don't need user authentication, you can create Public apps and embed them into your parent application using a public link.

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
import Retool from "react-retool";

function App() {
  return (
    <Retool url="https://retoolin.tryretool.com/embedded/public/f7607e1f-670a-4ebf-9a09-be54cf17181e" />
  );
}

export default App;

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.

Parent Window Query reading the value of the element

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

It's common to embed Retool apps into existing portals, tools, and applications. This makes it easier to provide a consistent and efficient app experience for external users, while making sure the data they see is secure.

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

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.

Prevent double logins

If you configure your web application and Retool to use the same IDP, a user might have to SSO into the web application, and then have to SSO again into the embedded Retool app. To avoid this, you can set up Retool to automatically sign the user in with SSO instead of displaying a login screen. This works when the user has an existing, authenticated session on the IDP.

To configure this, set one of these environment variables to true in your docker.env file.

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

Public apps

📘

Public apps and Retool plans

Public apps are only available on 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 editor and click the Share button in the top right. Select the Public tab and click Enable public link.

🚧

Public apps are not secure

You can add password protection to public apps but password protection isn't a robust authentication method. Don't put sensitive data in public Retool apps, even with password protection enabled.

Enabling a public access link

The following example is a demo app from our Quickstart guide.