Manage RBAC with the Retool API

Use the Retool API to programmatically manage roles, role grants, and object permissions.

Use the Retool API to programmatically manage roles, role grants, and object permissions at scale. This is useful for automating access provisioning, scripting onboarding workflows, and managing user invites, including assigning role grants to individual users, which is not available through the Settings UI.

All endpoints use the base path /api/v2. For complete endpoint details, request schemas, and response examples, see the Retool API reference.

Prerequisites

You need a Retool API token with the appropriate scope before making requests. See Configure Retool API authentication for instructions on creating a token.

Under Scopes, locate the Permissions card and select Read or Write based on the task you want to perform. Selecting Write automatically includes Read.

Task	Required scope
Read roles, role grants, and access lists	Permissions: Read
Create, update, or delete roles and role grants	Permissions: Write
Grant or revoke object permissions	Permissions: Write

Role and permission endpoints require Retool API version 2.9.0 or later.

Manage roles

Use the /api/v2/role_permissions/roles endpoints to create and manage organization roles and object roles programmatically. You can also manage roles through the Settings UI; refer to Create an organization role and Create an object role.

The available operations include:

• List roles: GET /api/v2/role_permissions/roles returns each role's id, name, object_scopes, organization_scopes, and whether it is a default role. Save each id to use when creating role grants.
• Create a role: POST /api/v2/role_permissions/roles accepts a name, optional description, and the permission scopes to assign. Both object_scopes and organization_scopes are required; pass an empty array for any category where no scopes apply.
• Update a role: PATCH /api/v2/role_permissions/roles/{roleId} updates any combination of fields. Changes apply immediately to all groups assigned the role. Default roles cannot be updated.
• Delete a role: DELETE /api/v2/role_permissions/roles/{roleId} removes the role and immediately deletes all of its grants. This action cannot be undone, and default roles cannot be deleted.

For request schemas, valid scope values, and response details, see the Roles endpoints in the API reference.

Manage role grants

A role grant assigns a role to a subject (a user, user invite, or group). Grants can be universal (applying across all objects covered by the role's scopes) or object-scoped (limited to a specific object or folder).

Use the /api/v2/role_permissions/role_grants endpoints to create and manage grants:

• Create a role grant: POST /api/v2/role_permissions/role_grants. For a universal grant, include only role_id, subject_type, and subject_id. For an object-scoped grant, also include object_type and object_id. Supported subject_type values are user, userInvite, and group. Supported object_type values are app, folder, workflow, agent, resource, and resourceFolder.
• List all role grants: GET /api/v2/role_permissions/role_grants returns every grant in your organization.
• List grants for a subject: GET /api/v2/role_permissions/role_grants/{subjectType}/{subjectId} returns only the grants for a specific user, user invite, or group.
• Delete a role grant: DELETE /api/v2/role_permissions/role_grants/{roleGrantId} removes a single grant by its id. The subject immediately loses the permissions granted by that role.
• Remove grants for a subject: POST /api/v2/role_permissions/remove_role_grants_for_subject removes all grants for a role and subject combination in a single request. Include object_type and object_id to target only the object-scoped grant for a specific object.

For request schemas and response details, see the Role grants endpoints in the API reference.

Manage object permissions

Use the /api/v2/permissions endpoints to grant or revoke direct access to specific objects, and to query who has access to what.

Access levels

The following access levels apply when granting or viewing permissions on objects:

Access level	Retool UI label	Description
view	Use	Can open and use the object
edit	Edit	Can modify the object
own	Own	Full control, including managing access

The API uses view where the Retool UI displays Use. These refer to the same access level.

Available operations

• Get the access list for an object: GET /api/v2/permissions/accessList/{objectType}/{objectId} returns all users, user invites, and groups with access. Each entry includes an accessLevel and sources indicating how the subject received access: direct (explicit grant), universal (from a universal role grant), groups (inherited through group membership), or inherited (inherited from a parent folder). Supported objectType values are app, folder, resource, workflow, and agent.
• List objects a subject can access: POST /api/v2/permissions/listObjects returns all objects of a given type that a user or group has access to. Set include_inherited_access to true to include access inherited through folder or group membership. Supported object_type values are app, folder, resource, and resource_configuration.
• Grant permissions on an object: POST /api/v2/permissions/grant grants a user or group access to a specific object. Supported object types are app, folder, screen, resource, and resource_configuration. For screens, also provide appId. The response returns the subject's full access list after the grant is applied.
• Revoke permissions from an object: POST /api/v2/permissions/revoke removes a user or group's access to an object. The response returns the subject's remaining access list.

For request schemas and response examples, see the Permissions endpoints in the API reference.