Skip to main content

Automate user onboarding using the Retool API

Learn how to programmatically onboard users to your Retool instance with the Retool API.

Retool API is currently in beta. Reach out to your Retool account team to get access.

To onboard teams to Retool, you often need to grant them the ability to build apps with new or existing resources. This can include:

  • Creating app and resource folders
  • Creating permission groups
  • Setting folder permissions
  • Provisioning users

Performing these tasks manually can be difficult to scale, but you can use the Retool API to automate these steps.

This guide outlines how to use the permissions and folder endpoints in the Retool API to onboard new users. If these users must operate in isolation from other teams, with their own resources, software development lifecycle, and release process, consider creating a Space for them.

Requirements​

The Retool API is available to cloud organizations and self-hosted organizations running v3.18 or later. API users must generate access tokens to authenticate. This guide assumes you have an access token with Read and Write scopes for users, permissions, and Spaces.

In this guide, replace space-domain with the domain of your Space or organization, e.g., organization.retool.dev or custom-space.organization.retool.dev.

1. Create an app folder​

The following command creates a top-level app folder named Support. The response contains the ID of the newly created folder; save this for a later step.

curl -X POST https://{space-domain}/api/v2/folders -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"name": "Support", "parent_folder_id": null, "folder_type": "app"}'

2. Create a resource folder​

The following command creates a top-level resource folder named Support resources. The response contains the ID of the newly created folder; save this for a later step.

curl -X POST https://{space-domain}/api/v2/folders -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"name": "Support resources", "parent_folder_id": null, "folder_type": "resource"}'

3. Update and create permission groups​

By default, the All users group has Use access to apps and resources. To ensure new Retool users have restricted access unless they're explicitly added to a permission group, set the universal access level for All users to None.

If you don't know the ID for the All users group, use the GET /groups endpoint to retrieve it.

curl -X PATCH https://{space-domain}/api/v2/groups/1 -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"operations": [{"op": "replace", "path": "universal_app_access", "value": "none"}]}'

Next, create a new permission group. Save its ID for later steps.

curl -X POST https://{space-domain}/api/v2/groups -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"name": "Support team", "universal_app_access": "none", "universal_resource_access": "user", "members": []}'

4. Set folder permissions​

Grant the newly created permission group access to the new app and resource folders with the following command. Replace GROUP_ID with the ID of your new permission group, and APP_FOLDER_ID and RESOURCE_FOLDER_ID with the IDs of your new app and resource folders.

curl -X POST https://{space-domain}/api/v2/permissions/grant -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"subject": {"id": GROUP_ID, "type": "group"}, "object": {"id": APP_FOLDER_ID, "type": "folder"}, "access_level": "edit"}'
curl -X POST https://{space-domain}/api/v2/permissions/grant -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"subject": {"id": GROUP_ID, "type": "group"}, "object": {"id": RESOURCE_FOLDER_ID, "type": "folder"}, "access_level": "edit"}'

5. Provision and map users​

Create users in Retool.

curl -X POST https://{space-domain}/api/v2/users -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{"first_name": "Test", "last_name": "User", "active": true, "email": "testuser@retool.com"}'

Use the newly created user IDs to add users to the new permission group, and optionally set any certain users as admins.

curl -X POST https://{space-domain}/api/v2/groups/{GROUP_ID}/members -H 'Authorization: Bearer $BEARER_TOKEN' -H 'Content-Type: application/json' --data '{[{"id": USER_ID, "is_group_admin": false}]}'

6. Wrap up​

You can confirm the onboarding flow correctly created app folders, groups, and users from the Settings > Permissions page. You should see the newly created permission group, and within it, a new member. The Apps and Resources tabs should reflect the new apps and folders.

To further streamline onboarding, you can add the Retool API as a resource and create an app or workflow to trigger these steps based on user input.