Skip to main content

Administration quickstart

Learn about the fundamental concepts of Retool administration.

This guide serves as an introduction to Retool administration. It covers many of the concepts and terminology you would come across when managing or working within a Retool organization. After reading this page, you should have a good understanding of the fundamentals for organizations and users.

The sections below follow the structure of the admin Settings navigation, so you can explore each area as you read.

A Retool organization is a distinct collection of users and data. Organizations operate separately from one another, have their own configuration settings, and are where users share access to work.

Each cloud-hosted organization has its own .retool.com subdomain, such as https://example.retool.com. Self-hosted organizations use the URL for their deployment and may have multiple instances.

Loading diagram...

Overview​

When you open Settings as an admin, the Overview provides a central place to set up your organization and respond to pending user requests.

Account​

The Account settings contain your personal Retool profile, including your name, password, and individual preferences.

Management​

The Management settings configure the core building blocks of your organization.

Spaces​

Spaces are an organizational feature that allow you to create multiple isolated Retool organizations. These spaces exist within the same parent organization and provide a multitenant experience. Each space has its own:

  • Subdomain of your Retool organization (e.g., space1.example.retool.com).
  • SSO configuration.
  • Source Control configuration.
  • User accounts and permission groups.
  • Retool Database.
  • Data (folders, apps, workflows, resources, etc.)
Loading diagram...

Spaces are useful when:

  • Your teams want to have separate source control repositories and sets of apps available to them.
  • You have isolated use cases which don't overlap with the rest of your Retool usage: e.g., you want to create a suite of “performance review” apps or an external portal, each with its own set of users, apps, and resources.
  • You want to delegate administration of Retool to a distributed set of admins, based on the apps they’ll be overseeing.

Environments​

Environments represent the stages of your development lifecycle, such as staging and production. Each environment stores its own resource credentials so apps and workflows connect to the appropriate data source as changes move toward production.

Retool API​

The Retool API enables Retool admins to programmatically manage different aspects of their organization, such as:

  • Access control
    • Users
    • Groups
    • Permissions
    • SSO
  • Apps and themes
  • Resources and resource environments
  • Folders for apps, resources, and workflows
  • Spaces
  • Source Control

Retool also implements a subset of the SCIM 2.0 API. This adheres to the SCIM 2.0 Protocol that is used by identity providers (e.g., Okta) to automatically provision users and map groups.

While there is overlap between functionality in the Retool API and SCIM 2.0 API, use the Retool API for automating operations when possible.

Retool events​

Retool Events allow organizations to build workflows that trigger automatically in response to actions taken in Retool. These workflows can then perform custom actions, such as sending custom onboarding emails to new users or notifying admins about certain actions that occur.

You can even configure branding options to replace Retool's built-in email notifications with workflows that send custom transactional emails with a reply-to address at your domain. When doing so, you should set up appropriate alerts as error handlers in your workflows.

Read the Retool Events workflow tutorial to learn more.

Configuration variables​

Configuration variables store reusable values, such as API base URLs, that you can reference across resources and queries. Secret values are encrypted and hidden after you save them.

Plans & billing​

The Plans & billing settings show your current subscription, user and usage counts, and billing details. Refer to the billing and usage documentation for more information.

Monitoring​

The Monitoring settings help you track activity, changes, and the health of your organization.

Usage analytics​

Usage analytics report on app, query, and user activity so you can understand adoption across your organization.

Audit logs​

Audit logs record administrative and user actions for security and compliance review. You can stream them to external tools such as Datadog or Splunk.

Source control​

Source control connects your organization to a Git provider so you can version, review, and deploy changes to apps and workflows.

Observability​

Observability exports logs, metrics, and traces to monitoring tools so you can track the health and performance of your deployment.

Permissions​

The Permissions settings control who belongs to your organization and what each user can access.

Users​

Refer to the billing and usage documentation to learn more about the different user types that relate to billing.

A Retool user is a Retool account that belongs or has access to an organization. Users represent the people with access to the organization and its data. Retool uses email addresses as the identifier for users.

When a user signs up, Retool associates them with an existing organization if the user meets one of the following conditions:

  • They use an invitation from an existing organization.
  • Their email address domain matches one configured by an existing organization to automatically add users from that domain.
  • They use an SSO provider configured for an existing organization.

Retool uses the email address as the identifier for a user and associates it with an organization at signup. This can be an existing organization if the user meets certain conditions or a new organization for which the user is the primary admin.

If the user doesn't meet these conditions during signup, Retool prompts them to create a new organization for which they become the primary admin.

Admins can see draft apps for all users in the organization using the Users' drafts filter. Drafts are enabled by default. Admins can toggle off this feature by navigating to Settings > Beta and turning off Drafts folders.

External users​

Organizations can embed web apps into their own web-based applications for use by external users, such as customers, vendors, or partners. An external user is not considered part of a Retool organization and can only access apps for which they have access.

External users priced at the same rate as on the Team and Business plans. However, usage for external use cases varies and the default pricing might not work for everyone. If you're pre-product or have hundreds of thousands of users, talk to our team to learn more.

Refer to External users for more information about external users.

Groups​

Permission groups bundle access to apps, resources, workflows, and agents. Assign users to groups to control what they can build and use.

Roles​

Roles control access to organization settings. Assign roles to determine which users can configure Retool itself.

User attributes​

User attributes are custom properties, such as region or department, that you assign to users and reference to control access and personalize app behavior.

Authentication​

Retool manages authentication of users for your organization. The available methods and process depend on your subscription plan and whether you use an SSO identity provider (IdP). Retool organizations on every plan can use Sign in with Google. Organizations on the Enterprise plan can configure additional SAML and OIDC providers.

Regardless of authentication method, new users must be added to relevant permission groups to grant them required access. You can either configure the SSO authentication flow to handle this automatically or you can manually configure user permissions.

Retool supports the following sign-in methods:

  • Sign in with Google: Sign in using your existing Google account. Retool creates a new organization if you're not an existing user. If your organization uses Google Workspace and all users share the same domain, users can select Sign in with Google and log in automatically to the same Retool organization. If you attempt to sign in with Google and there is no existing organization, Retool creates one and assigns you as an administrator.
  • Retool account: Retool accounts use an email address and password, which operates separately from Sign in with Google. You can specify a set of domains from which to allow users with a matching email address to join. Navigate to Settings > Advanced settings, then add one or more domains to the Auto-join domain section. You then specify whether users with a matching email address can request to join or join automatically for that domain. When auto-join is disabled, anyone who signs up to Retool with a username and password creates a new organization, regardless of whether the email address shares a domain with an existing Retool organization. To join an organization using email and password instead of creating a new one, they need to receive an invitation.

Single sign-on (SSO)​

SSO is a user authentication tool that enables users to securely access multiple applications and services using one set of credentials. Rather than require users to create additional usernames and passwords for Retool, you can centralize logins to a single identity provider (IdP). SSO is primarily used for authentication, though Retool also supports syncing groups for authorization.

IAM credentials​

IAM credentials let Retool authenticate to cloud provider services, such as AWS, using managed identity credentials instead of static access keys.

Features​

The Features settings let you enable and configure optional Retool capabilities.

AI​

The AI settings control which Retool AI capabilities and models are enabled for your organization.

Beta​

The Beta settings contain opt-in feature flags for functionality that is still in development. Admins can enable these features for the organization.

Mobile​

The Mobile settings configure organization-wide behavior for Retool Mobile apps, such as biometric verification and offline caching.

Customization​

The Customization settings let you tailor the appearance and capabilities of your organization.

Branding​

Branding customizes the appearance of your organization, including its name, logo, and login page, to match your company's identity.

Themes​

Themes define reusable color and style settings that you apply across apps for a consistent appearance.

Internationalization​

Internationalization lets you upload and manage translations so apps can display content in multiple languages.

Custom component libraries​

Custom component libraries let you build and share your own React components for use across apps in your organization.

External apps​

External apps let you publish Retool apps as standalone, externally accessible pages for users outside your organization.

Advanced settings​

Advanced settings contains organization-wide configuration that doesn't fit elsewhere, such as authentication enforcement, data retention periods, and other administrative toggles.