> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retool

> Connect Retool to Serval to sync users and permission groups, provision group membership through access requests and reviews, and call the Retool API from workflows.

## 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.

<Warning>
  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.
</Warning>

## What the Retool integration enables

| Capability | Description |
| - | - |
| User sync | Background ingestion of Retool users (name, email, active state, seat type) into Serval's directory, with targeted single-user refresh. Users on external-user seats are marked as guests. |
| Group sync | Background ingestion of Retool permission groups as Serval resources with a Member entitlement. Each group's default access levels (apps, resources, workflows, query library) are shown as its description so reviewers can see what membership grants. |
| Access provisioning | Retool group membership backs Serval access requests and reviews: granting access adds the user to the group, revoking removes them. Both are idempotent, and an existing member is never re-added, so group admins keep their admin flag. |
| Post-provision verification | After a grant or revoke, Serval re-reads the single membership to confirm the change landed. |
| On-demand group lookup | Import a group you just created in Retool by name without waiting for the next scheduled sync. |
| Group Management bundle | Prebuilt workflows: list groups, get the target user's Retool profile and groups, and add or remove the target user from a group by name. |
| Retool API request | Typed access to the identity-and-access subset of the Retool API v2: users, groups, permissions and roles, access requests, invites, user attributes, spaces, folders, apps, resources, Retool workflows and their runs, usage, organization settings, data security policies and the IP allowlist. |

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.

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Open the API settings">
    In Retool, open **Settings > API**. Creating tokens requires an admin.
  </Step>

  <Step title="Create a token">
    Click **Create token**, name it (for example `Serval`), and select the scopes it should carry.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Copy the token">
    Copy the token when it is shown; Retool does not display it again.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Retool connect form">
    In Serval, find the Retool integration and open its connect form.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Paste the token">
    Paste the token into **API Token** exactly as Retool displayed it, with nothing added before or after.
  </Step>

  <Step title="Submit">
    Submit the form. If the connection cannot be created you may see "Failed to connect service" or "Failed to install integration".
  </Step>
</Steps>

<Warning>
  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.
</Warning>

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:

| Health check | What it verifies | Success message | Failure message |
| - | - | - | - |
| Test Retool Connection | Authentication, by reading one user. | "Successfully authenticated with Retool" | "Unable to connect to Retool." followed by what the status code suggests: a rejected token (401), a missing scope or plan (403), or a wrong URL (404). |
| List Retool Users | The `users:read` scope. | "Successfully read users from Retool (found \[number])" | "Unable to list users from Retool." |
| List Retool Groups | The `groups:read` scope. | "Successfully read groups from Retool (found \[number])" | "Unable to list groups from Retool." |
| Read Retool Group Members | Reading one group's membership, which group sync and provisioning depend on. | "Successfully read members of group "\[name]" (found \[number])" | "Unable to read group members from Retool." |

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".

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Every health check fails with 403 on a valid token">
    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.
  </Accordion>

  <Accordion title="Health checks fail with 404 on a self-hosted instance">
    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.
  </Accordion>

  <Accordion title="Two Retool Cloud organizations on one team">
    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.
  </Accordion>

  <Accordion title="Group admins keep their admin flag">
    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.
  </Accordion>

  <Accordion title="Disabled users still appear in group rosters">
    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.
  </Accordion>

  <Accordion title="No manager, department or title data">
    The Retool user record carries none of these, so Serval's directory takes them from your HR or identity source, not from Retool.
  </Accordion>

  <Accordion title="A group created in Retool does not show up yet">
    Group sync runs on a schedule. Use the on-demand lookup in Serval's resource picker to import a group by name right away.
  </Accordion>

  <Accordion title="Custom workflows see Enterprise-only responses as 403">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Retool integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.