Configure Retool Embed for Cloud organizations

Learn how to configure your Cloud organization to use Retool Embed.

πŸŽ‰

beta

Retool Embed is in beta and only available to users on the Enterprise plan. You can book a demo with our team to learn more about embedding Retool.

To embed Retool applications from your Retool-hosted organization into a website like https://example.com, you need to ensure that Retool is on the apex example.com domain or a subdomain like retool.example.com. Because Retool is the hosting provider, you need to make some changes to your DNS configuration.

This guide explains how to set up a custom domain on your Retool-hosted organization to support embedding through Retool Embed. Additional functionality, like logins and direct use of apps with custom domains, is not supported.

πŸ“˜

Some web browsers, like Safari, block third party cookies by default. Since Retool sets cookies when authenticating users, attempting to authenticate the embedded Retool app across domains is not possible in these browsers, unless you change your browser's cookie privacy settings.

1. Configure DNS

DNS configuration needs to be completed with the tooling you use to manage your top level domain name. This is often the registrar where you registered the domain, or a DNS provider such as Cloudflare or AWS.

Create an A record mapping either the top level domain or subdomain to Retool’s IP addresses:

  • 35.92.202.168
  • 35.92.202.169
  • 35.92.202.170

Retool recommends against using wildcard * DNS entries for your configuration as these can expose you to domain takeovers.

DNS changes can take up to 24 hours to propagate in some cases. To validate that your DNS is configured and propagated, you can use the dig command on the command line:

$ dig retool.example.com +nostats +nocomments +nocmd

; <<>> DiG 9.10.6 <<>> retool.example.com +nostats +nocomments +nocmd
;; global options: +cmd
;retool.example.com.  IN A
retool.example.com. 120 IN A 35.92.202.168

2. Configure Retool

Navigate to /settings/branding in your organizations Retool settings. Under Add a custom domain, enter the domain name in the text box.

A screenshot of the retool branding settings page showing custom domains

The domain briefly enters a pending state while Retool provisions HTTPS certificates and updates internal infrastructure to support the new domain. An error state likely indicates that the DNS wasn't updated to point to Retool. If this occurs, verify that your DNS is updated and that dig shows the correct IP addresses, and then retry verification.

After a few minutes, the domain should be configured.

3. Using Retool Embed

After a custom domain is set, Retool Embed works as described in the Retool Embed quickstart. As is the case with self-hosted instances, the API request to generate the embed URL should point to https://<your_custom_domain>/api/embed-url/external-user, and the signed embed URL will use the custom domain you set up.