Create an object role

Create and manage object roles to control group access to apps, resources, workflows, and agents in Retool.

note

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

Use object roles to grant groups consistent, role-based access to apps, resources, workflows, and agents. You define the access level and whether it applies to all objects of a type or to specific objects only.

Retool includes default object roles for each built-in group (Admin, Editor, and Viewer). You can create custom object roles to grant specific access levels to custom groups.

Create an object role

Object role creation is a two-part process: first name the role, then configure its permissions.

1. Navigate to Settings > Roles.
2. Click the Create Role dropdown and select Create object role.
3. Enter a name and optional description for the role (for example, Billing App Owner).
4. Click Next.
5. For each object type you want to include, set an access level: Use, Edit, or Own. Object types with no access level set are excluded from the role.
6. For each included object type, toggle Apply universally on or off:
   • On: The role applies to all current and future objects of that type across the organization.
   • Off: The role applies only to the objects or folders you select when you assign the role to a group.
7. Click Create.

For example, a role that grants Edit access to apps with Apply universally on lets the assigned group edit every app in the organization, including apps created later. The same role with Apply universally off lets the group edit only the apps or folders you select when you assign it. For more information, refer to Grant types.

When Apply universally is turned on for a role, the object type displays a Universal badge in the role editor.

Object types you can include in a role: Apps, Workflows, Agents, Resources, and Backend Functions.

note

Default object roles (Admin, Editor, Viewer) cannot be edited or deleted.

Manage an object role

From the role's detail page in Settings > Roles, you can edit its permissions or use the Manage dropdown to rename it or delete it.

Edit role permissions

1. Navigate to Settings > Roles and select the role.
2. Go to the Object permissions tab.
3. Update the access levels or the Apply universally toggle for any object type.
4. Click Save.

Changes apply immediately to all groups assigned the role.

Change name or description

1. Navigate to Settings > Roles and select the role.
2. Click Manage and select Change name / description.
3. Update the name or description.
4. Click Save.

Delete a role

1. Navigate to Settings > Roles and select the role.
2. Click Manage and select Delete.
3. Confirm the deletion.

When you delete a role, all groups assigned the role lose those permissions immediately.

View object permissions

You can view a group's or user's effective object permissions from several places in Settings.

Groups page

1. Navigate to Settings > Groups and select a group.
2. Go to the Object Permissions tab.
3. Toggle between View by: Object (objects the group can access) and View by: Role (roles assigned to the group).

Users page

1. Navigate to Settings > Users and select a user.
2. Go to the Object Permissions tab.
3. View the user's effective permissions, including those inherited through group membership.

Roles page

1. Navigate to Settings > Roles and select an object role.
2. View the role's scopes on the Object permissions tab and its group assignments on the Assignments tab.

Next step

Assign roles to groups

Assign object roles to groups with universal or individual access.