Skip to main content

Manage user seats

Manage seat types for users in your organization.

Managing user seats applies only to Enterprise organizations using Named Seats — Retool's per-seat-type pricing model.

Users who do not have a builder seat in your organization can request an upgrade when they need to perform a builder-only action, such as publishing an app, editing a workflow, or deploying an agent. Since assigning a builder seat affects your organization's billing, all requests must be approved by an admin.

Admins can also configure default seat types for users provisioned through JIT or embedded apps.

Request builder access​

Internal users can build apps in the editor, but a builder seat is required to publish an app and make it available to other users in your organization. Retool prompts users to request a builder seat when they attempt a builder-only action, such as:

  • Publishing an app.
  • Editing a workflow.
  • Deploying an agent.

The Upgrade to a Builder seat dialog describes the benefits of a builder seat. Click Request upgrade to submit the request for admin approval.

A user can only have one open request. Any subsequent request supersedes the previous one.

Review builder access requests​

Builder access requests appear in the Requests tab of the Users settings page and on the Overview page, where you can approve or decline them without navigating away. Admins receive an email notification whenever a user submits a request.

To review a request:

  1. Navigate to Settings > Users.
  2. Select the Requests tab. Each row shows the user's name, current seat type, requested seat type, and when the request was submitted.
  3. Click Approve to upgrade the user to a builder seat, or Reject to deny the request.

When you approve a request, the user's seat type updates immediately and they receive an email confirmation. When you reject a request, the user's seat type is unchanged and they receive an email notification that their request was denied.

Configure seat types for JIT user provisioning​

Retool assigns a seat type to users created through JIT user provisioning. If you don't configure a default seat type, Retool uses the least permissive eligible seat type:

Assigned seat typeExternal appsConditions
Internal user Default
External user User's email domain doesn't match any admin's
Internal user User's email domain matches an admin's (treated as an internal employee)

To override this behavior:

  1. Navigate to Settings > Single Sign-on (SSO).
  2. Select your Custom SSO provider.
  3. Under the Optional section, toggle on JIT user provisioning.
  4. From the Default seat type for JIT users dropdown, select Builder, Internal user, or External user.

Self-hosted instances can also configure the default seat type for JIT users with the JIT_DEFAULT_SEAT_TYPE environment variable. Set it to builder, internalUser, or externalUser.

Configure seat types for embedded apps​

The embed URL endpoint accepts an optional seatType parameter to specify the seat type for the embedded app user. Only internalUser and externalUser are supported.

If seatType is omitted, the user is assigned an internal user seat. This includes calls to the /api/embed-url/external-user endpoint. You must pass seatType: "externalUser" when you want external user seats for embedded users.

Example cURL
// Replace APP_UUID, GROUP_IDs, UUID with actual values
curl -X POST "https://retool.example.com/api/embed-url/external-user" \
  -H "Authorization: Bearer retool_01hn417x8zsaqfye58r995re18" \
  -H "Content-Type: application/json" \
  -d  '{ "landingPageUuid": APP_UUID, "groupIds": GROUP_IDs, "externalIdentifier": UUID, "seatType": "externalUser"}'