How Retool Embed works

Retool Embed is a way to let external users––partners, vendors, customers––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.

Rather than relying on internal teams to manage customer workflows, you can embed Retool apps into your product to make the experience self-serve. For example, you could:

• Build an onboarding flow for customers to upload documents and update their account information.
• Create a dashboard that allows users to configure product settings (e.g., enable beta features, change pricing plans, etc.)
• Build a supplier portal for external users to manage their inventory, invoices, and to track sales.

Each of these experiences could be built in Retool and then integrated into your product using the Retool Embed flow.

How Retool Embed works

Retool Embed doesn't change much in how you build in Retool. You still use resources, components, and queries to build your apps.

There are a few additional steps to provide access and embed apps after you build them. These steps are covered in more detail in the Retool Embed quickstart, but a brief overview is provided below.

Access tokens and permission groups

To embed apps, you need to create an access token with the Embed scope. This token allows you to create sessions for embedding Retool apps.

After creating the access token, you need to create permission groups for your users. These groups determine the apps individual users can access. For example, you might give access to apps according to the subscription level customers are on.

Embed URL

The embed URL is a single-use link scoped to a user session for an application. Your backend will make a POST request to Retool with the access token, permission groups, app info, and user info to generate the URL. After Retool returns the embed URL, you use it in an iframe to display the app.

Requirements and recommendations

To use Retool Embed, you must:

• Set up a custom domain for your Retool instance.
  • If Retool is your hosting provider, follow the Cloud instructions to add A records to your DNS provider.
  • If you are running self-hosted Retool, configure your custom domain in your cloud provider's settings.
• Turn Prevent Query Spoofing on.
• Host Retool on the same top-level domain as the parent application.
• Use HTTPS when generating embed URLs.
• Have already built a Retool app to embed.

If you're self-hosting, in addition to these requirements, Retool also recommends that you:

• Deploy Retool at scale.
• Externalize the Postgres backend database to make Retool containers stateless.

When you deploy Retool at scale, you can have separate instances for internal and external use. This helps with separation of concerns, performance, scalability, managing updates, development lifecycle, and permissions.

For external use cases, you might also want to use Source Control to release your apps. This allows you to use a Git-based workflow to release apps to external users.

Other ways to embed Retool apps

Retool Embed is the supported way to authenticate users into embedded Retool apps, but there are other ways you can embed Retool. See Sharing Retool apps for more.