Manage Retool deployments with a hub and spoke model

Learn how to use the hub-and-spoke model to effectively manage Retool at scale.

The hub and spoke model is an organizational model that can set up your teams to implement and scale Retool effectively. Using this model, a centralized group of administrators own Retool deployments and:

  • Delegate permissions and oversee access
  • Manage the application Software Development Lifecycle (SDLC)
  • Perform maintenance and upgrades

This model enables developers to build tooling for end users. It is the most common approach used by organizations running Retool.

Hub and spoke model

Organizational setup

With hub and spoke, teams (spokes) are centralized around a central team (the hub).


The hub (central team) is responsible for:

  • Initial setup: Infrastructure
  • Initial setup: Access controls
  • Initial setup: Folder structure
  • Initial setup: Resource integrations
  • Theming and branding
  • Internal wiki and best practices
  • Upgrades


The teams (spokes) that surround the hub are responsible for:

  • App development
  • Folder-level permissions
  • Team-specific usable code

After deploying Retool, the hub is responsible for making sure that the spokes can build and use apps efficiently. This is achieved by properly configuring access controls, delegating ownership to approval processes, and building onboarding guides.

Role-Based Access Controls in Retool

Retool’s user and group permissions allow administrators to control how users use, edit, and own apps or resources. User assignment to groups can be done through your Retool organization's settings or through a supported identity provider.

Manage group permissions

Group permissions can only be set using your Retool organization's settings. If you need to onboard multiple teams, we recommend you organize apps into folders and apply group permissions to them.

For example, a Driver Operations team at a ride-sharing startup is replacing their Google Sheets workflows with a more resilient Retool app and Postgres database. The administrator can:

  1. Create a folder named Driver Ops which will contain all of the apps for the Driver Operations team.
  2. Create a permissions group named Driver Ops Team and grant Use permissions to the Driver Ops folder. By default, all apps are then available to use by this team, but they cannot yet edit them. Individual permissions on a per-app basis can also be applied at a later time.
  3. Invite the Driver Operations team members to the Driver Ops Team group.
  4. Grant Use access to the Postgres database connected to the Retool instance.
  5. Optionally assign a Group Admin with Own access to the Driver Ops Team group. This grants the Group Admin the ability to modify, add, and remove new users for this group.
  6. Create a permission group called Eng and grant Own or Edit permissions for the Driver Ops folder. This group can then build and edit apps for the Driver Ops team.
  7. Grant Use access to the Postgres database connected to the Retool instance.
  8. Invite the engineering team to this Eng group.

As your organization grows, you can use the same process to add new teams and app builders.

User management through an Identity Provider

We recommend integrating Retool with an existing identity provider (IdP) if you need to provision and manage many groups of stakeholders, such as Okta, Azure, or Google. Retool supports SAML and OpenID SSO, as well as just-in-time (JIT) user provisioning.

As new teams and user groups are added, you can configure role-mapping between your identity provider and Retool as needed. New team members are automatically provisioned with Retool accounts (via SCIM or Group Push), streamlining the onboarding process.


User provisioning and access controls to applications and resources should be overseen by a centralized group of stakeholders—usually across DevOps, SecOps, SSO teams, and Engineering. Setup of SSO requires instance-level configuration, so it’s important to delegate an owner for the Retool deployment so that they can quickly set environment variables and easily redeploy the Retool instance.

We recommend working with our Deployed Engineering team to identify which environment variables need to be configured.

Resource connections

The central team has control over the resources used in your Retool apps that allow teams to safely build apps with them. In addition to our granular permissions model for Resources, the central team can restrict requests at the database or API level.

Lock down requests at the API level

If you have OpenID SSO integrated with Retool and are building apps on top of REST endpoints, you can pass the JWT obtained from the login as a header to each request. This ensures the Retool user is always authorized to make these requests. If you don’t have OpenID SSO set up but have a separate authorization server, you can also define a custom authentication workflow to let your backend authenticate a user into your API.

Lock down requests at the database level

If you’d like control both read and write access to certain databases, we recommend creating separate database users (and multiple resources), then assigning the proper permission groups to those resources.

At scale, for both new group and resource provisioning, teams should create a ticketing process in which access is reviewed by the central team.

Onboarding guides

As you’re setting up your Retool deployment, it’s important that teams can quickly onboard onto Retool and deliver value for end users. We recommend you create organization-specific guides on the following topics:

  • Overview of the organizational structure of teams who own and build in Retool.
  • How to identify a Retool use case.
  • How to obtain a Retool account.
  • How to obtain access to resources for your use case (APIs, databases, and permissions).
  • Useful resources and documentation on development (pointing to Retool documentation).
  • Application promotion and release process.
  • How to help onboard operations teams.
  • How to build Retool apps (e.g., video of using the App editor to build a new app).

You can use our technical onboarding template (Google Doc) to get started.

Application development

At scale and in production, having the right Retool app development process is key to ensuring a smooth and stable product for end users. Because it is so easy to build a Retool app, it is important that the proper safeguards are in place to prevent bugs and ensure high-quality updates. Source Control and Releases are two key features to enforce a development lifecycle that meets the needs of enterprise clients.

Source Control in Retool

Source Control allows organizations to manage changes to their Retool applications using pull requests on remote source control management (SCM) providers, such as GitHub and GitLab. Instead of making changes directly to an application, changes are made on a separate branch.

When an app is protected, it can no longer be modified without reviewing and merging the changes in a source control provider (like GitHub or GitLab). This workflow mirrors a typical SDLC in which no engineer can push code directly to the master branch.

At scale, this level of protection is critical so that production applications in Retool cannot simply be modified by changing something in the Retool editor. Additionally, it enables multiple editors to work on the same application at the same time.

Source Control enables users to sync applications across multiple instances of Retool. A common approach is to have staging and production instances of Retool be configured as read-only, pulling changes from the staging and master branches. All development happens via branches in a development instance and code is merged into the master branch. See our recommended workflow for using Source Control in Retool.

Reviews and ownership

Using the hub-and-spoke model, the hub is responsible for the Source Control integration and can assign owners to review pull requests. All applications live within a single repository owned by the hub.

When the hub has configured the required access controls and permissions, it should not be heavily involved in the day-to-day development of apps, but may coordinate releases to production.

Versions and Releases

Releases lets you version and release app changes to your users. This method can also be used in conjunction with Source Control.

Although you can configure your application to use the master branch, you may still not want it to update every time the branch is updated. In these cases, you can create versioned releases and control when updates are available to your users.

Developer ergonomics and reusability

Retool has built-in features that make it easy to avoid duplicative work when writing queries and building apps. At scale, with potentially hundreds of apps, Retool also gives you the ability to ensure your apps are discoverable and visually consistent.

Reusing groups of components using modules

You can use modules to share groups of components across Retool apps. This encourages code reuse and delivers a more consistent end-user experience across your applications. Changes to a module are immediately reflected across all apps in which it is used.

We recommend using modules when you’re reusing the same set of components across apps. Modules let you specify inputs and outputs, allowing you to centralize logic that is easily reused across different use cases.

Improve discovery with navigation

The Navigation component can help users find apps and makes it more convenient for end users to navigate across apps and other online resources in a single workflow. For multi-page applications, or for groups of apps dedicated to specific workflows, create a navigational menu once as a module, then reuse it across apps.

Reuse queries

The Query Library enables you do create and reuse queries in the same way as modules function to reuse components. You can write, share, and control access to queries from the Query Library, which is important if you have many apps leveraging the same data source.

Any queries in individual apps should be moved into the Query Library if you find the same queries being written across apps. Queries within the Query Library also have permissions, so if you have complex or sensitive queries and want a specific team to own them, you can manage access through your organization settings.

Customize style with themes

You can create themes with custom color palettes that can be easily applied to applications with one click. Themes provide a way for builders to build applications that match existing brand guidelines used in their organization.