Skip to main content

Configure Spaces

Learn how to set up Spaces for your self-hosted Retool instance.

Available on:Enterprise plan
Beta

Retool Spaces is in beta and available on self-hosted Retool versions 3.18 and later. Reach out to your Retool account team to get access.

Retool Spaces are an organizational feature which allow you to create multiple isolated Retool organizations on the same underlying Retool instance. Each Space has its own:

  • Subdomain
  • SSO configuration
  • Source Control configuration
  • User accounts and permission groups
  • Retool Database
  • Folders, apps, workflows, modules, queries, resources, etc.

Spaces are useful when:

  • Your teams want to have separate source control repositories and sets of apps available to them.
  • You have isolated use cases which don't overlap with the rest of your Retool usage: e.g., you want to create a suite of “performance review” apps or an external portal, each with its own set of users, apps, and resources.
  • You want to delegate administration of Retool to a distributed set of admins, based on the apps they’ll be overseeing.

See the guide to governance on Retool to learn when to use Spaces, multiple instances, and permission groups.

Initial setup and Admin Space​

By default, new Retool instances are configured with one Space. This Space looks and behave exactly the same as a new instance without Spaces—you spin up the instance, and then create the first account, which becomes its admin, in this Space. The first Space is the Admin Space. When you upgrade an existing instance to a version with Spaces, the existing organization becomes the Admin Space.

If you anticipate needing multiple Spaces, you may want to keep the Admin Space free of apps, and use it only for superadmin responsibilities.

Create Spaces​

Admins on the Admin Space can create and manage spaces from Settings > Spaces, or use the Retool API. Each Space must have a name, description, and associated domain, which cannot change after the space is created. Spaces can automatically copy over SSO, branding, and theme settings from the current organization when created.

Domains​

The domain must be configured to point to the current instance and have a correct SSL certificate. Users can navigate directly to the Space using this domain.

note

To avoid configuring a domain for each new Space, you can set up a wildcard subdomain in your DNS settings—e.g., *.retool.mycorp.com—and secure it with a matching wildcard SSL certificate. You can then create new Spaces with arbitrary subdomains that match the wildcard without having to update your DNS again. You can set any level of subdomain—for example, *.mycorp.com, *.retool.mycorp.com, and *.retool.prod.mycorp.com are all possible subdomains.

Log in to new spaces​

The admin of the new Space can log in using the following methods:

  • If SSO was copied over for the new Space, Retool creates an admin account for this superadmin on the new Space. They can use SSO to log in directly to the new Space.
  • If SSO hasn’t been configured for the Space, the admin needs to log in the same way they log in to a new Retool instance, by resetting the password associated with their email address.

Spaces that aren't the Admin Space can also have their own admin users. These users have admin privileges, but they cannot create new Spaces. New Spaces can only be created from the Admin Space by its superadmins.

Configure Spaces​

Admins can customize SSO, invite users, configure source control, and update settings on Spaces, the same way they update settings on existing organizations.

tip

You can use the Retool API to programmatically configure Spaces. See the guide for more information.

Spaces and SSO​

Each Space has its own SSO configuration, but you can copy SSO settings from other Spaces. Since each Space has a different domain name, you must confirm that a correct callback URL is configured in your IdP. Most IdPs allow you to add multiple callback URLs; you need to add one for each Space. Some IdPs, like Auth0, support wildcards in callback URLs.

Okta's Retool integration accepts a single domain name in its configuration, so you need to configure a separate Okta app for each Space, or use the generic OIDC or SAML app configuration to provide multiple callback URLs.

Spaces can also use different SSO settings depending on their use cases. For example, a general-purpose Space with apps for everyone at your company may use JIT provisioning. A Space for use with only a finance team might need explicit user provisioning.

Spaces and Source Control​

Each Space has its own separate Source Control configuration, so it can connect to a different Git repository or an entirely different SCM provider. For each new Space, you need to set up Source Control to point to the repository that should be linked to the space.

Spaces can also connect to the same Git repository. For example, you might want to use Spaces to represent different dev, staging, and prod environments. These Spaces function the same as multiple instances connected to the same Git repository—you can choose which branch to point to by default, and sync changes when commits are merged into this branch.

Spaces and Retool Database​

Each Space has its own Retool Database. If you already configured an external PostgreSQL cluster to use on your self-hosted instance, you can connect the new Space's Retool Database to the same cluster. Each Space automatically creates a new database in the cluster.

Switch between Spaces​

Users can have accounts in multiple Spaces and switch between them. From the navigation bar, users can select the Spaces in which they have an account. Users must log into each space separately.