Create an object role

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

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 universally across 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 & Permissions.
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, choose how the role applies:
   • Universal on: The role applies to all current and future objects of that type across the organization.
   • Universal off: Access is scoped to specific objects or folders, which you define when assigning the role to a group.
7. Click Create.

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

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

Manage an object role

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

Edit role permissions

1. Navigate to Settings > Roles & Permissions and select the role.
2. Go to the Object permissions tab.
3. Update the access levels or universal settings 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 & Permissions 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 & Permissions 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 & Permissions 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.