Permissions best practices

🚧

Permission groups are only available on Business or Enterprise plans. You can see how they work by signing up for a 30-day trial of our Business plan trial.

As a Retool admin, you can set User Permissions to control which users have access to folders, applications, resources, and more. This document goes over the best practices to manage users effectively.

Default permission groups

There are four default permission groups for every org:

• All users: every user within your organization will belong to this group, and the membership will not be altered.
• Viewer: a group with configurable membership where every member has “Use” access to all of Retool.
• Editor: a group with configurable membership where every member has “Edit” access to all of Retool.
• Admin: members of this have “Own” access to all applications, folders, and resources, and can modify organization level settings.

The access levels for default permission groups cannot be modified. The following table shows how the Use, Edit, and Own access levels affect applications, resources, and folders.

🚧

Resource folders are available on Retool Cloud and self-hosted Retool v2.92 or higher.

In addition to providing these default groups, Retool also allows you to set Group Admins for any custom permission group. The Group Admin can manage membership to their group by adding and removing users.

Recommended permissions setup

Separate development and production environments

You might want to give Retool builders their own development sandbox while controlling end-user access to Retool applications and resources. Separating these environments gives builders the flexibility to test use cases, explore Retool, and build applications in a non-production environment.
Read more about using multiple environments to develop against staging resources.

Use folders and groups

It's helpful to use a combination of app folders, resource folders, and permission groups to organize access for Retool developers and end-users.

Example setup and workflow

Consider the following example user profiles:

• Bob is a non-technical support agent who runs ad-hoc scripts to troubleshoot customer accounts.
• Alice is a technical builder on the Engineering team tasked with building applications for the Support organization.
  Using Retool, Alice would like to quickly build frontends for Bob and his team so they can service customers faster.

Single instance setup

This setup allows Alice to build applications, in isolation from Bob, using resources she can fully access. When she's ready to give the Support team access to an app, she can move it from the Eng Sandbox folder to the Support Apps folder.

1. Create public folders

First, create an application folder and a resource folder, each named Public.

Next, in the All Users permission group:

• In the Apps tab under Select access type, choose Define specific app access.
• Select the Use checkbox next to the Public app folder.
• Repeat the above step in the Resources tab for the Public resource folder.
• This grants every new Retool user access to the applications and resources in these folders.

2. Create groups and folders for Support

On the main App page, create an application folder named Support Apps. On the main Resources page, create a resource folder named Support. Bob and his Support team will use Retool applications that live in the Support Apps folder.

Next, in Settings > Permissions, create a permission group named Support. Set the Use checkbox on the Support Apps application folder and the Support resource folders. When Use access is set on a folder, all users in the group have Use access to new applications and resources in the folder.

You can also optionally assign a group admin of the Support permission group to easily manage membership for the team.

3. Create groups and folders for Engineering team

In Settings > Permissions, create a permission group named Engineering.
Repeat steps 1-4 in the Support team setup with the following modifications:

• Name the resource folder Eng and the application folder Eng Sandbox.
• Assign Own access to the Engineering application and resource folders.
  Finally, assign Own access to the Support Apps and Support folders. This allows Engineering to add applications to the folders when they're ready to go.

Workflow

Alice can develop applications in the Eng Sandbox using resources from the Eng folder, and later move them apps to Support Apps for Bob to use.

If Alice needs to make changes to an existing app while it's in active use by the Support team, using a combination of Releases and Multiple Environments can make the the development workflow much smoother. This way, Alice can test against staging endpoints, and when ready, publish a Release for end-users.

Multi-instance setup

🚧

This guide is for Enterprise users running Self-hosted Retool across multiple instances. Book a demo with Retool's Sales team to learn more about running Retool on-premise.

If you're self-hosting Retool across multiple deployments, you may have a dedicated development instance isolated from production. This permissions setup assumes the recommended workflow for using Source Control for development and production instances.

This guide uses the same Alice and Bob user profile as the single-instance guide. Alice and her team want to build applications in a development instance, and Bob needs to use those applications in a production instance.

Permissions on the development instance

A separate development instance lets Retool builders the ability to easily and safely create applications against non-production endpoints and resources.

1. Create public application and resource folders

First, create an application folder and a resource folder, each named Public.
Next, in the All Users permission group:

• In the Apps tab under Select access type, choose Define specific app access.
• Select the Edit checkbox next to the Public app folder.
  Every new Retool user will be granted edit access to applications and resources added to these folders.

2. Create folders and groups for Support team

For Alice and her team, create an application folder called Support applications and a resource called Support.

Next, create a permission group called Support Eng. Set Own access for both the Support Apps and Support application and resource folders.

When Own access is set on the folders, these permissions apply to all users in the group when applications and resources are added to those folders. Because only the Support Eng permission group has Own access, only engineers can build applications that live in the Support application folder.

You can also optionally set a group admin for the "Support" permission group to easily manage membership for the team.

Permissions on the production instance

A separate production instance gives Retool end users access to only production-ready applications which hit production endpoints and resources.

1. Create public application and resource folders

Create an application and a resource folder, each named Public.
Next, in the All Users permission group:

• In the Apps tab under Selected access type, choose Define specific app access.
• Select the Use checkbox next to the Public app folder.
• Repeat the above step for the Public resource folder.
  Every new Retool user will be granted access to new apps and resources added to those folders.

2. Create folders and groups for Support team

For Bob and his team, create an application folder name Support Apps and a resource folder named Support. The Support team will use apps that live in the Support Apps folder.

Next, create a permission group named Support. Set Use access to the Support Apps application folder and the Support resource folder. Use access is now applied for all users in the group when apps and resources are added to those folders.

You can optionally set a group admin for the Support permission group to easily manage membership for the team.

3. (Optional) Create a group for Engineering team

For Alice and her team, create a permission group for the Engineering team. Give the group Own permission for the Support and Public folders. When using Releases, this will allow engineers to create new releases per application.

Workflow

This workflow assumes use of the recommended workflow of Source Control.

Alice can now build apps against resources which she has full access to in the developer instance, in isolation from Bob. When she is ready to give the Support team access to an application she protected using Source Control, she can open a Pull Request and merge her changes. Once her changes propagate to the production instance, end-users will see the latest changes reflected in the app in production.

If Alice needs to make changes to an app while it’s in use by the Support team, she can use Releases to test her changes in staging before publishing a Release to production.