Organizations and users quickstart

Learn about the fundamental concepts of Retool organizations and users.

This guide serves as an introduction to Retool organizations and users. 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.

Introduction

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.

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

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.

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.

An email address can only be associated with one organization. If a person needs to access multiple Retool organizations, they must create a user account for each with different email addresses.

If a user signs up and creates a new organization instead of joining an existing one, they must archive their account and organization first.

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 end users 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 apps and users for more information about external users.

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.

Sign in with Google

Retool supports Sign in with Google. You can 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, 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 will 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.

Retool API

Retool API is currently in private beta on Retool Cloud and Self-hosted Retool.

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