Object roles

Understand how object roles work in Retool, including universal and individual access grants.

note

The object permissions feature is currently rolling out to cloud instances. It is not yet available on self-hosted instances.

Object roles contain permission scopes that control access to Retool objects: apps, resources, workflows, and agents. Unlike organization roles, which govern access to settings pages, object roles govern what users can do with the things they build in Retool.

Object Permissions tab

When object roles are in use, the Object Permissions tab on each group's detail page shows a unified view of that group's object access, including both access granted through role assignments and any access configured directly in the Apps, Resources, Workflows, and Agents tabs.

The tab offers two views:

• View by: Object: Lists accessible objects organized by type, showing the access level and whether access is universal or scoped to a specific object or folder.
• View by: Role: Lists access organized by the role that granted it.

How object roles work

An object role defines a set of object-level permission scopes (e.g., "Edit all apps", "Use all resources"). When you assign an object role to a group, every member of that group inherits those permissions.

A single role can include scopes for multiple object types. For example, a role that grants Edit access to apps and Use access to resources.

Grant types

Each object type included in an object role has a grant type. You set it with the Apply universally toggle when you create the role.

• Universal (Apply universally on): The role covers every object of that type in the organization, including objects created later. Use this for teams that need broad, ongoing access, such as a platform team that manages all resources.
• Individual (Apply universally off): The role covers only the objects and folders you select each time you assign it to a group. The role defines the access level, and each assignment defines what that access applies to. Use this for teams that work with their own set of objects, such as a marketing team that owns a few apps.

The grant type is a property of the role, not of the assignment. A single role cannot be universal for one group and individual for another. To grant the same access level both ways, create two roles.

The tradeoff is maintenance compared to control. Universal access needs no upkeep as your organization grows, but it grants access to everything. Individual access stays narrow, but someone has to grant access each time a new object needs it.

Best practice

For most organizations, start with individual access and expand to universal only when a team genuinely needs access to everything. This follows the principle of least privilege and makes it easier to audit access.

Folder inheritance

When you scope an object role to a folder, the permission applies to all objects within that folder, including objects added later. If an object is moved to a different folder, it inherits the permissions of its new parent folder.

Default object roles

Retool automatically creates a default object role for each built-in group:

Group	Default object role
Admins	Own access to all apps, resources, workflows, and agents
Editors	Edit access to apps, workflows, and agents; Own access to resources
Viewers	Use access to all apps, resources, workflows, and agents

Default object roles can only be assigned to their corresponding default groups. You cannot assign the Admin Universal Object Permissions role to a custom group.

How object roles relate to direct access

Object roles work alongside direct access configured on a group; you can use both together. Direct access is configured per object type (Apps, Resources, etc.) on the group's detail page. The Object Permissions tab shows the combined picture.

Neither method overrides the other; permissions are additive. If a group has Use access to an app via direct configuration and Edit access via a role, members get the higher Edit access.

Available scopes

Object type	Use	Edit	Own
Apps	View all apps	Edit all apps	Own all apps
Resources	View all resources	Edit all resources	Own all resources
Workflows	View all workflows	Edit all workflows	Own all workflows
Agents	View all agents	Edit all agents	Own all agents

For what each access level lets users do, see Permission levels.

Next steps

• Create an object role: Step-by-step instructions for creating and assigning object roles.
• Permission levels reference: What Use, Edit, and Own access let users see and do.