Skip to main content

​
About Retool

Retool is a platform for building internal tools. Access to those tools is governed by Retool permission groups: a user’s groups decide which apps, resources and workflows they can use or edit. Serval connects to your Retool organization with an API token, keeps its user directory and group catalog in sync, and provisions access by adding users to and removing them from groups. The integration is marked Beta in Serval’s connect UI. Authentication: A Retool API token (bearer token) created in Retool’s Settings > API. The token’s scopes fully determine what Serval can read and write; Serval requests no permissions of its own. Where requests go: Retool Cloud organizations are served from api.retool.com; a self-hosted instance serves the API itself at https://<your-instance>/api/v2. Serval derives the right host from the Retool URL you enter. Data sync: Background sync keeps Serval’s user directory and group catalog (with memberships) current. The Retool API has no change feed, so every sync is a full walk; both run on Serval’s standard schedule.
The Retool API’s user, group, permission and usage endpoints are available on the Retool Enterprise plan only. On the Business plan the health checks fail with a 403 and the integration cannot sync users or groups. Self-hosted instances must run a release that includes API v2.

​
What the Retool integration enables

The add and remove workflows ship with installer approval by default; the two read-only workflows run without approval.

​
Get your credentials

You need the host you sign in to Retool at and an API token.
1

Note your Retool URL

For Retool Cloud this is your organization’s subdomain, for example acme.retool.com; a Space host such as engineering.acme.retool.com works too, since every cloud host is served by the same API. For self-hosted Retool it is your instance’s hostname, for example retool.example.com.
2

Open the API settings

In Retool, open Settings > API. Creating tokens requires an admin.
3

Create a token

Click Create token, name it (for example Serval), and select the scopes it should carry.
4

Select scopes

Serval needs users:read and groups:read for sync and the health checks. Add groups:write if Serval should manage group membership. Add further read or write scopes only for the Retool API calls your own workflows make.If the dialog offers only Retool RPC and Custom Component Libraries, with no Users or Groups scopes, the organization is not on an Enterprise plan. Retool’s user, group and permission endpoints exist only on Enterprise, so this integration cannot read that organization until the plan changes.
5

Copy the token

Copy the token when it is shown; Retool does not display it again.
A Retool API token acts with every scope it carries, for the whole organization. Grant the smallest set of scopes that covers your Serval workflows.

​
Connect in Serval

1

Open the Retool connect form

In Serval, find the Retool integration and open its connect form.
2

Enter your Retool URL

Enter the host from the step above into Retool URL, with or without https://. A trailing /api/v2 is tolerated, any other path is rejected, and plain http:// is rejected because Serval only reaches Retool over HTTPS.
3

Paste the token

Paste the token into API Token exactly as Retool displayed it, with nothing added before or after.
4

Submit

Submit the form. If the connection cannot be created you may see “Failed to connect service” or “Failed to install integration”.
Serval does not contact Retool when you submit the form, so an invalid token still connects “successfully”. Always check the health check results after connecting; when you connect from an application’s setup form, Serval runs them automatically right after the connection saves.
When you later edit the connection, the saved token displays as an obfuscated value. Changing the Retool URL requires pasting the token again: a token belongs to one organization, and Serval will not carry it over to another host.

​
Verifying the connection

Serval runs four health checks against your Retool organization: If your organization has no groups yet, the last check passes with “Connected to Retool but the organization has no groups to read members from”.
All four health checks are read-only, so they can be fully green while provisioning still fails. If a grant or revoke returns a permission error, add the groups:write scope to the token.

​
Gotchas and troubleshooting

The user, group and permission endpoints are Enterprise-only. Below Enterprise the token is accepted but every call Serval makes is denied, and the health-check message repeats Retool’s own reason: “This API endpoint is not available on your plan” means the plan, while “API token is missing one of users:read” means the token was created without the scope. The tell on the Retool side is the Create access token dialog: on a plan without the API it offers no Users or Groups scopes at all. Check the plan before rotating tokens.
The URL is wrong, or the instance runs a release that predates the endpoint. Enter the hostname only (no path), confirm it serves https://<host>/api/v2/spec, and compare the spec’s version with your release.
Connect each organization separately with its own URL and token. Serval keeps them apart by the URL you enter, even though both are served from api.retool.com.
Retool’s add-member call sets the member’s admin flag. Serval checks membership first and never re-adds an existing member, so provisioning a user who is already a group admin leaves them an admin.
Retool keeps disabled users in their groups. They sync as members, and the user sync marks them deactivated, so reviews show them as inactive members rather than dropping them.
The Retool user record carries none of these, so Serval’s directory takes them from your HR or identity source, not from Retool.
Group sync runs on a schedule. Use the on-demand lookup in Serval’s resource picker to import a group by name right away.
Every Retool API family except User Invites and User Attributes needs the Enterprise plan, and every call needs a token scope that covers it. The scope an endpoint needs is named in its description in the API reference.
Need help? Contact support@serval.com for assistance with your Retool integration.