Skip to main content

Configure role-based access control

Use role-based access control (RBAC) to create roles and assign permissions to groups.

Role-based Access Controls Availability
CloudGenerally Available
Self-hosted Edge 3.300 or laterGenerally Available
Self-hosted Stable Expected in Q1 2026.

Role-based access control (RBAC) allows organization admins to assign access to permissions settings via roles, which can then be assigned to groups. It is managed via the Settings > Roles & Permissions page. This approach offers several advantages:

  • Principle of least privilege - Grant only the minimum permissions needed.
  • Reusable roles - Define a role once and apply it to multiple groups.
  • Simplified management - Update a role's permissions and all assigned groups inherit the changes.
  • Clear audit trail - Track who has access to what through role assignments.

Feature differences by plan​

The RBAC system is extended on Enterprise plans to include the full range of organization-level administrative permissions (see Admin Granularity for more information). This provides granular control over who can manage specific settings without granting full admin privileges.

  • Business plan customers can assign a limited number of permissions.
  • Enterprise plan customers can assign all organization-level permissions. Refer to the Admin permissions reference for a full list of permissions.

For example, a Business plan customer can create a role that grants access to the query library. Whereas, an Enterprise customer with admin granularity can additionally create roles that grant access to SSO configuration, billing management, or user attribute management.

  • Available permissions: There are 11 permission scopes available:
    • View account details
    • View users
    • Edit query library
    • View query library
    • View audit logs
    • Manage usage analytics
    • Manage themes
    • Allow access to unpublished releases
    • Manage draft apps
    • Use Assist with Build and Ask mode
    • Use Assist with Ask mode only
  • Can assign: Only non-critical settings.

Use Groups to control who can access apps, resources, workflows, and agents. Refer to the permission groups page for more information.

Create a role​

A role contains a set of organization permissions that grant access to specific settings pages. You can create custom roles tailored to your organization's needs.

Only organization admins can create, modify, and delete roles. Roles are created, assigned, and managed the same way for both the Business and Enterprise plans.

To create a role that assigns permissions:

  1. Navigate to Settings > Roles & Permissions.
  2. Click Create Role.
  3. Enter a descriptive name (e.g., SSO Manager or Billing Administrator).
  4. Add a clear description of the role's purpose.
  5. Select the checkbox next to the permissions that should apply to the role. Certain permissions control access to a specific settings page within your organization. For example, the Manage branding permission allows access to the branding settings page.
    1. You can use the search or filter functionality to find specific permissions:
      • Search: Type keywords like "billing" or "user" to filter permissions.
      • Filter by type: Use the dropdown to view permissions by category, such as User management and Configuration.
      • Select all/Deselect all: Quickly select or clear all permissions in a section.
    2. The Permissions preview pane displays a summary of the role's permissions as you make changes.
  6. Click Save changes.

Permissions available for Business plan customers.

Permission categories​

Permissions are organized into categories:

  • User management: User attributes, custom SSO, account details, user list.
  • Query library: View and edit the query library.
  • Organization: Spaces, source control, usage analytics, billing, audit logs.
  • Customization: Branding, themes, custom components, Retool events.
  • Configuration: Environments, configuration variables, Retool AI, IAM credentials, observability, mobile settings.
  • Assist: View and edit Assist.

Create focused roles with only the minimum permissions needed. You can assign multiple roles to a group so that members receive a combination of their permissions.

Assign the role to groups​

You can assign roles to groups from either the Roles & Permissions or Groups page.

Assign roles to a group​

The Groups settings page is where you manage all groups for your organization. To change roles for a group, select the group and click Modify role assignments.

Assign groups to a role​

Once created, assign the role to groups:

  1. From the Roles & Permissions page, select your role.
  2. Click the Assignments tab.
  3. Click + Add group assignment to select which groups are assigned the role. You can also click > to expand a group and view a complete list of its members.
  4. Select the groups that should have this role.
  5. Click Save.

Users in the assigned groups now have the permissions granted by the role.

Manage roles​

You can view, edit, and delete roles from the Roles & Permissions settings page.

View roles​

The Roles & Permissions page displays all roles in your organization, including:

  • Default roles - Pre-configured roles that cannot be deleted (e.g., Admin).
  • Custom roles - Roles you've created.

Click on a role to view its details, including:

  • Permissions - The organization settings this role grants access to.
  • Assignments - Groups that have this role assigned.

Edit a role​

To modify an existing role:

  1. Navigate to Settings > Roles & Permissions.
  2. Select the role you want to edit.
  3. Click Edit role.
  4. Update the permissions as needed.
  5. Click Save changes.

Changes to a role automatically apply to all groups assigned that role.

Delete a role​

To delete a custom role:

  1. Navigate to Settings > Roles & Permissions.
  2. Select the role you want to delete.
  3. Click Delete role.
  4. Confirm the deletion.

Default roles (such as Admin) cannot be deleted. If you attempt to delete a default role, the option will be unavailable.

Best practices​

Follow these best practices when configuring RBAC:

Use the principle of least privilege​

Grant only the minimum permissions needed for users to perform their tasks. Create focused roles with specific permissions rather than broad roles with many permissions.

Example

Instead of creating a Settings Manager role with all configuration permissions, create separate roles like Environment Manager (environments only) and Theme Manager (themes only).

Create reusable roles​

Design roles based on common job functions rather than individual users. This makes roles easier to maintain and apply consistently across your organization.

Example

Create roles like Analytics Viewer, Branding Editor, or User Manager that can be assigned to multiple groups.

Combine multiple roles​

Assign multiple roles to a group when users need permissions from different areas. Users inherit the combined permissions of all roles assigned to their groups.

Example

A group might need both Analytics Viewer and Audit Log Reader roles to perform their duties.

Use descriptive names​

Give roles clear, descriptive names that indicate their purpose. Include the permission level in the name when appropriate.

Example

Use Branding Manager instead of Design Team Role or Theme Editor instead of Role 1.

Regularly audit role assignments​

Periodically review which groups have which roles assigned. Remove role assignments that are no longer needed.

Troubleshooting​

Why can't I delete a role?​

Default roles (such as Admin) cannot be deleted. These roles are created automatically when your organization is set up and are protected to ensure basic functionality.

Only custom roles that you've created can be deleted.

Can I assign roles to individual users?​

Currently, roles can only be assigned to groups, not individual users. To grant a role's permissions to a single user:

  1. Create a group for that user.
  2. Add the user to the group.
  3. Assign the role to the group.

What happens if a user belongs to multiple groups with different roles?​

Users inherit the combined permissions of all roles assigned to their groups. Permissions are additive—if any group grants a permission, the user has that permission.

Example

If a user is in Group A (with Analytics Viewer role) and Group B (with Branding Manager role), they have both analytics viewing and branding management permissions.

Can I see which users have a specific permission?​

Yes. To see who has access through a role:

  1. Navigate to Settings > Roles & Permissions.
  2. Select the role.
  3. Click the Assignments tab.
  4. Expand each group (click >) to view its members.

All members of assigned groups inherit the role's permissions.