canonical: https://jentic.com/apis/retool.com/retool

# Retool Admin REST API

The Retool Admin REST API lets a Retool organization's admins administer it from code: it adds and deactivates users, builds groups and their membership, organises folders and Spaces, grants and revokes access on objects for users or groups, and reads or changes the source control settings that link the organization to a Git provider. Requests go to your own Retool instance subdomain with a bearer token generated in Settings, and each token carries scopes for areas such as Users, Groups, Folders, Permissions, Spaces, and Source Control.

## For AI agents

Administer a Retool organization: add and deactivate users, manage groups and their members, grant or revoke use, edit, or own access, organise folders and Spaces, and read source control settings.

## Scope

Does not handle building or running Retool apps, querying Retool resources or databases, workflows, or billing. Use for administering Retool users, groups, permissions, folders, Spaces, and source control settings only.

## Capabilities

- Onboard a user with createUser, which takes a required email plus first_name, last_name, and metadata
- Deactivate or edit a user by setting active or metadata with updateUser on `/users/{userId}`
- Add users to a group by id with addGroupMembers on `/groups/{groupId}/members`, and remove one with removeGroupMember
- Create a group with universal_app_access and universal_resource_access levels such as none, use, edit, or own
- Grant or revoke a user's or group's use, edit, or own access on an object with `/permissions/grant` and `/permissions/revoke`
- List the objects a user or group can reach with `/permissions/list-objects`
- Point the organization at a GitHub, GitLab, Bitbucket, or Azure DevOps repo and default_branch through `/source_control/settings`

## Use cases

### Agent-run Retool onboarding through Jentic

An IT agent connected through Jentic searches by intent for adding a user to Retool, gets createUser and addGroupMembers with their schemas, creates the account from the new hire's email and name, and adds the returned user id to the right group. Group membership then decides which apps the person can use, so access follows the team they join.

Example prompt: POST /users with email 'dana@acme.com', first_name 'Dana', last_name 'Lee', then PUT `/groups/{groupId}/members` for the Support group with members set to the new user id

### Offboarding and access cleanup

When someone leaves, an agent sets active to false on their user with updateUser, removes them from each group with removeGroupMember, and checks `/permissions/list-objects` to confirm no object grants remain for that user. Any remaining direct grant can be removed with `/permissions/revoke.`

Example prompt: PUT `/users/{userId}` with active false, DELETE `/groups/{groupId}/members/{userId}` for each group, then POST `/permissions/list-objects` with subject {type: 'user', id: userId}

### Access review across groups

For a quarterly access review, an agent lists every group, pulls each group's members, and asks `/permissions/list-objects` what each group can reach. The result is a table of who can use, edit, or own which objects, ready for an owner to sign off or trim.

Example prompt: GET /groups, then for each group GET `/groups/{groupId}/members` and POST `/permissions/list-objects` with subject {type: 'group', id: groupId}, and compile the access levels

### Source control settings check

An agent reads `/source_control/settings` to confirm which provider, org, repo, and default_branch the organization syncs with, and can update them when a repository moves, for example from GitHub to GitLab.

Example prompt: GET `/source_control/settings` and report provider, org, repo, and default_branch

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/users` | Create a user |
| PUT | `/users/{userId}` | Update or deactivate a user |
| GET | `/groups` | List groups |
| PUT | `/groups/{groupId}/members` | Add members to a group |
| POST | `/permissions/grant` | Grant access to a user or group |
| POST | `/permissions/revoke` | Revoke access |
| POST | `/permissions/list-objects` | List objects a subject can access |
| GET | `/source_control/settings` | Get source control settings |

## Key resources

- **Users** — Organization members with email, names, active flag, and metadata
- **Groups** — Groups with universal app and resource access levels and member lists
- **Permissions** — use, edit, or own grants of objects to users or groups
- **Folders and Spaces** — Containers that organise apps and separate teams
- **Source control settings** — Git provider, org, repo, and default branch for the organization

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 87 / 100
  - Developer Experience & Jentic Compatibility: 59 / 100
  - AI-Readiness & Agent Experience: 48 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 73 / 100
- **View full report:** https://jentic.com/apis/retool.com/retool/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Retool Admin API by hand means templating your own instance subdomain into the base URL, generating a scoped bearer token in Settings, and paging users and groups with page and per_page. Through Jentic you install once, import the Retool Admin REST API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Retool puts the group id in the URL path (`/groups/{groupId}/members`), so a rule can pin your agent to one group's membership. You choose the operations it may call, so destructive ones like deleteUser, deleteGroup, or revokePermission are not included unless you add them.
- **Credential handling:** Your Retool API token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a user to a Retool group' or 'revoke edit access', and Jentic returns the matching Retool operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Okta API** — Identity provider for users, groups, and SSO
- **Auth0 Management API** — User and role management for your own applications
- **GitHub REST API** — Repositories, branches, and pull requests

## FAQ

### What authentication does the Retool Admin REST API use?

Per its OpenAPI spec, the API takes a bearer token in the Authorization header. You generate it in Retool under Settings, Retool API, and each token carries scopes for areas such as Users, Groups, Folders, Permissions, Spaces, Source Control, and App Themes. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time.

### Can I grant a group access to a Retool app with the API?

Yes. POST `/permissions/grant` takes a subject (type user or group, plus id), an object (type and id), and an access_level of use, edit, or own. POST `/permissions/revoke` removes a grant, and POST `/permissions/list-objects` shows what a subject can already reach.

### What are the rate limits for the Retool Admin REST API?

The OpenAPI spec does not specify rate limits. Check https://docs.retool.com/reference/api/ for current limits on your plan.

### Is there a Retool MCP server?

You don't need an MCP server to give your agent the Retool Admin REST API. Jentic connects it directly from the API Directory: import it, store your API token once, and your agent calls it. Operations are found by intent when needed, so no extra tool definitions sit in your agent's context.

### How do I add a user to a Retool group through Jentic?

Install Jentic One, add the Retool Admin REST API from the directory, set your instance subdomain, and store a token scoped for Users and Groups. Your agent searches for 'add a user to a Retool group', gets PUT `/groups/{groupId}/members` with its schema, and sends the members array of user ids. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Retool Admin REST API?

Yes. Write a rule that allows only GET and PUT on `/groups/42/members`, so the agent can read and add members of that one group but cannot delete users, change permissions, or touch source control settings, and every call it makes is logged.
