# How to Set Up Role-Based Access Control in Retool

- Tool: Retool
- Difficulty: Intermediate
- Time required: 20-30 min
- Compatibility: Retool Cloud and Self-hosted
- Last updated: March 2026

## TL;DR

Retool's RBAC system is configured in Settings → Roles & Permissions. The four default groups (Admin, All Users, Editor, Viewer) cover most use cases. Business+ plans allow custom groups with granular scopes. Use {{ current_user.groups.includes('groupName') }} in component Hidden or Disabled properties to show/hide features based on the current user's role.

## Org-Wide Roles and Permission Groups in Retool

Role-based access control (RBAC) in Retool operates at two levels: the organization level (who can build apps, manage resources, and access settings) and the application level (who can view or edit specific apps). This tutorial focuses on the organization-level RBAC, which is the foundation for controlling what different user types can do in your Retool instance.

Retool provides four built-in permission groups: Admin (full access), Editor (can build apps, cannot manage settings), Viewer (can use apps, cannot edit them), and All Users (a group every member belongs to). Business and Enterprise plans allow creating custom groups with specific permission scopes tailored to your organizational roles.

In addition to system-level groups, you can reference current_user.groups in any {{ }} expression to conditionally show or hide UI elements, gate actions, or filter data based on the logged-in user's group membership.

## Before you start

- Admin access to a Retool organization
- Retool Cloud or Self-hosted instance
- Basic understanding of Retool's user management
- Business+ plan required for custom permission groups (built-in groups work on all plans)

## Step-by-step guide

### 1. Navigate to Settings → Roles & Permissions

Log in as an Admin. Click the gear icon in the top-right corner of the Retool editor or navigate to your-retool-instance.com/settings. In the Settings sidebar, find and click 'Roles & Permissions' (may appear as 'Permission Groups' depending on your Retool version). This page lists all existing permission groups and their assigned users.

**Expected result:** The Roles & Permissions page shows the four built-in groups: Admin, All Users, Editor, and Viewer, with their member counts.

### 2. Understand the four built-in permission groups

Retool ships with four default groups that cannot be deleted. Admin: full access to everything — app creation, resource management, user management, settings, billing. Editor: can create and edit apps, create and use resources, but cannot manage users or billing. Viewer: can use (run) apps but cannot edit or create them. All Users: automatically includes every member of the organization — permissions set here apply universally.

```
// Built-in groups and their key capabilities:
// Admin:
//   - Create/edit/delete apps
//   - Manage resources (databases, APIs)
//   - Manage users and groups
//   - Access org settings and billing
//   - Access audit logs

// Editor:
//   - Create/edit apps
//   - Create/manage resources
//   - Cannot manage users, billing, or org settings

// Viewer:
//   - Use (run) apps
//   - Cannot create or edit apps
//   - Cannot access resources or settings

// All Users:
//   - Every member is automatically in this group
//   - Useful for org-wide defaults (e.g., read access to certain apps)
```

**Expected result:** You understand what each built-in group can and cannot do before customizing.

### 3. Create a custom permission group (Business+ plans)

On Business and Enterprise plans, click '+ New group' in the Roles & Permissions page. Name the group after your organizational role (e.g., 'Sales', 'Support', 'Finance'). After creating the group, click on it to edit its permission scopes. You will see a list of scope checkboxes organized by category: Apps, Resources, Workflows, Settings, Users. Enable only the scopes needed for that role. Free and Pro plans are limited to the four built-in groups.

```
// Example: Support Agent group configuration
// ✓ Use apps (can run apps they have access to)
// ✓ View app list (can see available apps)
// ✗ Create apps (cannot build new tools)
// ✗ Manage resources (cannot modify database connections)
// ✗ Invite users (cannot add team members)
// ✗ View audit log (no access to security logs)

// Retool Free/Pro: 11 permission scopes available
// Retool Business: 30 permission scopes available
```

**Expected result:** The custom group appears in the Roles & Permissions list. You can assign users to it and it appears in current_user.groups for members.

### 4. Assign users to permission groups

Click on a permission group to open its detail view. In the Members tab, click '+ Add member'. Select users from your org's user list to add them to the group. Users can belong to multiple groups — their effective permissions are the union of all groups they belong to. To remove a user, click the trash icon next to their name in the Members tab.

**Expected result:** Selected users appear in the group's Members list. Their Retool access now reflects the group's permission scopes.

### 5. Use {{ current_user.groups }} to gate UI elements

In any Retool app, the current_user object exposes the logged-in user's groups as an array of strings. Use this in {{ }} expressions to conditionally show, hide, or disable UI elements based on role. This gives you granular in-app access control that complements the system-level RBAC. Note: this is UI-level control — always enforce permissions at the query/API level as well.

```
// Show a Delete button only for Admin users:
// Button Hidden property:
{{ !current_user.groups.includes('admin') }}

// Show a Salary column only for HR or Admin:
// Table column Hidden property:
{{ !current_user.groups.some(g => ['hr', 'admin'].includes(g)) }}

// Show different views based on role:
// Manager view Container Hidden:
{{ !current_user.groups.includes('managers') }}
// Employee view Container Hidden:
{{ current_user.groups.includes('managers') }}

// Display current user info in a Text component:
{{ `Logged in as: ${current_user.fullName} (${current_user.groups.join(', ')})` }}
```

**Expected result:** UI elements show or hide based on the logged-in user's group membership, creating a role-specific interface.

### 6. Configure per-app access separately from org-wide groups

Beyond org-wide groups, each individual app has its own access control. In the app editor, click Share (top-right) to see the app's access list. You can grant individual users or groups Use (can run), Edit (can modify), or Own (can delete and share) access to the specific app. This is additive — a user needs both org-level permissions AND app-level access to use an app. The RBAC tutorial covers org-level; for app-level see the user permissions tutorial.

**Expected result:** The app's sharing settings show the access levels for each user and group. Changes take effect immediately.

## Complete code example

File: `JS Query: enforceRoleBasedQueryExecution`

```javascript
// Enforce role-based query execution server-side
// (UI-level checks are UX only — always enforce at query level too)

const userGroups = current_user.groups;
const userEmail = current_user.email;

// Define which groups can perform each action
const CAN_DELETE = ['admin', 'managers'];
const CAN_EXPORT = ['admin', 'finance', 'managers'];
const CAN_VIEW_PII = ['admin', 'hr', 'managers'];

// Check if user has required permission
function hasPermission(action) {
  const allowedGroups = {
    delete: CAN_DELETE,
    export: CAN_EXPORT,
    viewPII: CAN_VIEW_PII
  };
  return userGroups.some(g => allowedGroups[action]?.includes(g));
}

// Example: Guard a delete operation
if (!hasPermission('delete')) {
  console.warn(`User ${userEmail} attempted delete without permission`);
  utils.showNotification({
    title: 'Permission denied',
    description: 'Only Admins and Managers can delete records.',
    notificationType: 'error'
  });
  return;
}

// Proceed with the operation
await deleteRecord.trigger({
  additionalScope: { id: table1.selectedRow.data.id }
});

utils.showNotification({ title: 'Record deleted', notificationType: 'success' });
await getRecords.trigger();
```

## Common mistakes

- **Using current_user.groups for security-critical restrictions without backing them up with server-side query guards** — undefined Fix: UI checks (Hidden property, 'Only run when') can be bypassed by tech-savvy users. Add role checks in JS Queries that execute the sensitive actions as an additional enforcement layer.
- **Group names are case-sensitive — 'Admin' and 'admin' are different groups** — undefined Fix: Standardize on lowercase group names in your organization. Use current_user.groups.map(g => g.toLowerCase()).includes('admin') for case-insensitive checks.
- **Expecting RBAC changes to take effect without the user refreshing or re-logging in** — undefined Fix: Retool re-evaluates group membership on each page load. Permission changes take effect the next time the user refreshes or opens the app. For SSO users, a new SSO sign-in may be required.
- **Confusing org-level RBAC groups with app-level sharing permissions** — undefined Fix: Org RBAC (Settings → Roles & Permissions) controls what actions a user can perform across the org. App sharing (Share button) controls access to specific apps. A user needs both: the org-level permission to use apps AND specific access to the app.

## Best practices

- Always enforce permissions at the query level (in JS Queries), not just via Hidden/Disabled UI properties — UI-side checks are UX, not security.
- Keep group names lowercase and consistent (e.g., 'admin', 'managers', 'support') to avoid case-sensitivity bugs in current_user.groups.includes() checks.
- Use the 'All Users' group for baseline permissions that every org member should have, then grant additional scopes via specific groups.
- Audit permission group membership regularly — employees change roles, and stale group assignments create security gaps.
- On Business+ plans, create role-based groups that match your org chart (Finance, HR, Ops, Support) rather than creating permission groups per app.
- Document your RBAC design in a Retool app or wiki so new admins understand the intended role structure.
- When using SSO (SAML/OIDC), configure group mapping in your IdP to automatically assign Retool groups based on directory groups.

## Frequently asked questions

### What is the difference between Retool's RBAC and per-app permissions?

RBAC (Settings → Roles & Permissions) controls what a user can do across the entire organization — building apps, managing resources, accessing settings. Per-app permissions (Share button on each app) control which users or groups can view or edit that specific app. A user needs both: org-level permission to use apps AND app-level access to run the specific app.

### Can I restrict which databases a specific user group can query in Retool?

Yes, on Business and Enterprise plans. In Settings → Roles & Permissions, custom groups have granular resource access scopes. You can grant a group access to specific resources (e.g., read-only PostgreSQL) while denying access to others (e.g., write access or different databases). Free and Pro plans use the built-in Editor/Viewer distinction, where Editors have access to all resources.

### Does current_user.groups work in Retool public apps?

In public apps (unauthenticated), current_user is not available and current_user.groups will be an empty array or undefined. Always check that current_user exists before accessing its properties in apps that support both authenticated and unauthenticated access.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-set-up-role-based-access-control-in-retool
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-set-up-role-based-access-control-in-retool