Spaces tutorial

Learn how to set up Spaces for your organization.

Spaces Availability
Cloud	Generally Available	Enterprise
Self-hosted Edge 3.36 or later	Generally Available	Enterprise
Self-hosted Stable 3.33 or later	Generally Available	Enterprise

Retool Spaces is an organizational feature that allows you to split your Retool organization into multiple isolated ones, creating a multitenant experience. After enabling Retool Spaces, you retain your original organization as an Admin Space, and you can create any number of alternative spaces.

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: for example, 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 Retool Spaces, multiple instances, and permission groups.

Initial setup and Admin Space

Cloud-hosted organizations

Navigate to Settings > Spaces to enable Retool Spaces. This sets up Retool Spaces and provisions SSL certificates, which typically takes around five minutes. Once it is finished, you can begin to create spaces.

Self-hosted instances

By default, new self-hosted instances are configured with one space. This space looks and behaves 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. If you're self-hosting Retool, when you upgrade an existing instance to a version with spaces, the existing organization becomes the Admin Space.

If you anticipate needing multiple spaces, consider keeping the Admin Space free of apps, and use it only for superadmin responsibilities.

Create spaces

Admin users of 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 subdomain. You can choose to automatically copy over SSO, branding, and theme settings from the current organization.

Configure domains

Cloud-hosted organizations

The domain of your Admin Space does not change. If the domain on which you enable Retool Spaces is example.retool.com, every other space is automatically located as a subdomain (for example, testing.example.retool.com).

You can change the subdomain or create a custom domain for any space after it's created.

Self-hosted instances

If you self-host Retool, the domain of each space must point to the current instance and have a correct SSL certificate. Users can navigate directly to the space using this domain.

To avoid configuring a domain for each new space, you can set up a wildcard subdomain in your DNS settings—for example, *.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.

Retool expects the domain name to be passed via Host header to the backend. If your self-hosted instance has proxy or load balancer in front of Retool backend, make sure it's configured to set Host header to the host used in the original request.

Not all Identity Providers support wildcard domains. When setting up SSO for your spaces, make sure your Identity Provider is compatible with wildcards.

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 their exisiting SSO account to log in directly to the new space.
• If SSO hasn’t been configured for the space, the admin needs to log in by resetting the password associated with their email address.

You can add users from any permission group to your space, including admin users. However, only admin users of the Admin Space can create new spaces.

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.

You can also 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 existing SSO settings to a new space when you create it. 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 might use JIT provisioning. A space for use with only a finance team might need explicit user provisioning.

SSO settings and environment variables

When you use environment variables to configure SSO settings, those settings apply to all spaces, unless you override them per space from Settings > SSO.

This applies to all SSO settings except those used for SCIM provisioning. The SCIM_AUTH_TOKEN environment variable only applies to the Admin Space and is not supported on other spaces. To use SCIM provisioning on a non-admin space, navigate to Settings > API, and create an access token with the scim scope.

Spaces and Source Control

To use Retool Spaces with Source Control, ensure you migrate your apps to Toolscript.

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 you want to link to the space.

Multiple spaces can also connect to a single Git repository. For example, you might want to use spaces to represent different dev, staging, and prod instances. 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 navigate between the spaces to which they belong. Users must log in to each space separately.

Copy across spaces

For organizations on the Enterprise plan on cloud instances and self-hosted instances on versions 3.41 and later, admins can copy apps, resources, Query Library queries, and workflows across spaces. The following applies to all copied items:

• Copies are unprotected in the destination space.
• Copied resources are created in the destination space's default resource environment.
• All dependencies except environment variables are copied to the destination space. You must configure environment variables in the destination space.
• Releases, permissions, and unit tests are not copied to the destination space.