Retool Security: Protecting Resources, Permissions and Self Hosted Deployments

Retool apps sit directly on production databases and APIs through shared resource credentials, so a builder with the wrong group membership or a leaked encryption key can reach data the business never meant an internal tool to expose. This guide covers how Retool controls access: permission groups, organisation and object roles, SSO, resource credentials and configuration variables, the Retool API, Source Control, audit logs and the environment variables that harden a self-managed deployment. Product facts come from Retool's own documentation, checked on 8 November 2026; hardening stances are NHI Mgmt Group guidance. It is written for platform owners, application security engineers and identity teams running Retool Cloud or self-hosted Retool. For the wider risks of citizen-built applications, see the Low-Code and No-Code Application Security Guide.

This is an independent guide from NHI Mgmt Group, based on Retool's public documentation as of November 2026. It is not sponsored or reviewed by Retool. Product features change, so confirm settings against Retool's current documentation.

Key takeaways

• Resources are shared non-human identities. A resource holds a database or API credential that every permitted app and workflow uses, so the account behind it must be least privilege and owned.
• Permissions are additive. Users get the combined roles of every group they belong to, plus any organisation role granted directly, so one stray group grants more than it looks.
• Keep secrets server-side. Secret configuration variables are never exposed on the frontend and are usable only in resource configurations and workflows; use them, or an external secrets manager, rather than values typed into apps.
• On self-hosted, two variables are the crown jewels. ENCRYPTION_KEY protects stored resource credentials and JWT_SECRET signs sessions; treat both as tier-zero secrets.
• Audit logs record queries, not just logins. Entries include the query, parameters and IP address, so they are both a detection source and sensitive data in their own right.

How identity and access work in Retool

People sign in to an organisation and are placed in groups. Groups hold organisation roles (org-wide settings) and object roles (apps, resources, workflows and agents). Apps and workflows reach data through resources, whose credentials are stored by Retool. Automation of Retool itself uses Retool API access tokens.

Access features depend on plan. Retool documents that Free and Team plans have default groups only, with no custom groups or roles; Business adds custom groups, organisation roles, object roles, direct per-object access and per-environment resource access; Enterprise adds admin granularity. Object roles are documented as not yet available on self-hosted instances, so check your version before designing around them.

Single sign-on: self-hosted Retool configures SAML with SAML_IDP_METADATA and OpenID Connect with the CUSTOM_OAUTH2_SSO_* variables. DISABLE_USER_PASS_LOGIN turns off username and password login so users must use SSO, and RESTRICTED_DOMAIN requires SSO for listed email domains. Group sync is available through SAML_SYNC_GROUP_CLAIMS (groups with the retool- prefix) or LDAP_ROLE_MAPPING, and SCIM_AUTH_TOKEN holds the shared secret for SCIM provisioning. Keep DISABLE_SAML_INRESPONSETO_VALIDATION at its default of false. See the Identity Provider and SSO Security Guide.

Admin roles and privileged access

Retool creates three default groups in every organisation; they cannot be edited, reassigned or deleted.

• Additive permissions: because a user receives the union of all their groups' roles, review effective access per user, not group by group. See the Least Privilege Techniques Guide.
• Direct grants are exceptions: Retool allows organisation roles to be granted directly to a user from Settings > Users as an exception. List these and remove them where a group would do.
• Universal grants include the future: a Universal object role on resources silently covers every resource created later, including new production databases.
• Break-glass: if you enable DISABLE_USER_PASS_LOGIN, plan how an admin recovers access during an identity provider outage before you need it. See the Break-Glass Account Guide.

Integrations, API tokens and service accounts

Resource credentials

On self-hosted deployments, Retool encrypts data in its PostgreSQL database, including database credentials and SSH keys, with ENCRYPTION_KEY. The documentation warns that changing the key without rotating means losing access to every resource created before the change. Setting USE_GCM_ENCRYPTION=true switches from AES-192-CBC to AES-192-GCM authenticated encryption, which requires ENCRYPTION_KEY to be set. Protection at rest does not limit what the resource can do, so:

1. Dedicated accounts per resource and environment: a production read replica account for reporting tools, a separate write account only where an app must change data, and separate staging credentials.
2. Least privilege in the database: grant the tables and operations the apps need, never the database owner role. Every user of every app using the resource acts with these rights.
3. Owners and inventory: each resource has a named owner and is listed with your other service accounts. See the Service Account Security Guide.

Configuration variables and secrets

Configuration variables can be marked secret with Mark variable as secret. Secret values are never exposed on the frontend and are available only in resource configurations and workflows; in workflows they are sanitised in block responses when single blocks are run. Values can differ per resource environment, with a Default Value as fallback, and only admins can create or edit them. They are encrypted on Cloud and stored in your PostgreSQL database when self-hosted. On self-hosted deployments, only environment variables with the RETOOL_EXPOSED_ prefix are readable by users, and SCOPED_SECRETS=true limits a secret to one folder of resources through the naming convention scoped__resources__<folder>__<secret>. For rotation without redeploying, Retool's documentation points to AWS Secrets Manager, HashiCorp Vault, GCP Secrets Manager and Azure Key Vault integrations. See the Secrets Management Guide.

Keep ENABLE_CLIENT_SIDE_CUSTOM_AUTH_BROWSER_CALLS at its default of false: when true, browser-side REST calls with custom authentication send all browser credentials, including on cross-origin calls.

Retool API tokens

Organisation admins create tokens under Settings > Retool API with a name, description and scopes: Source Control, Users, Groups, Folders, Permissions and App Themes (each Read or Write) and Data Security (Read). Write includes Read. The token is shown once and is sent as a Bearer token. Tokens created in a Space work only with that Space's endpoints. Users, Groups and Permissions write scopes can grant anyone admin access, so treat a token holding them as an admin credential: store it in a secrets manager, name its owner and purpose in the description, and create separate tokens per integration. See the API Key Management Guide.

Source Control

Retool Source Control supports GitHub, GitLab, AWS CodeCommit, Bitbucket and Azure Repos. Retool's best practices are to build on a staging or development instance and promote to production through multi-instance releases, keep branches open for a week or less, and add test deployments as a required check so invalid changes cannot reach main. Add branch protection and mandatory review in your Git provider so a single builder cannot ship to production alone. See the Git Repository Security Guide.

Logging and detection

Retool audit logs record user actions such as query runs and password resets, with the user, action and time, and detailed entries can include the query, parameters, IP address and response time. Admins view them at /audit. Logs are kept for one year; the page shows three months and the full year can be downloaded. On Cloud, Business and Enterprise customers can download a compressed CSV whose link expires after an hour. On self-hosted Enterprise, logs can stream to Datadog (version 3.38 or later) or Splunk (3.114 or later), and LOG_AUDIT_EVENTS=true writes events to stdout for a sidecar to collect. Events are also stored in the audit_trail_events table, with columns including actionType, userId, ipAddress, queryName and resourceName. See the SIEM Guide.

Metrics:

• Members of the Admins group, and organisation roles granted directly to users.
• Universal object role grants on resources (target zero for production resources).
• Production resources using accounts with write or owner rights, versus read-only.
• Retool API tokens holding Users, Groups or Permissions write scopes.
• Share of users signing in through SSO, and whether DISABLE_USER_PASS_LOGIN is set.

Hardening baseline

Rollout order:

1. Export users, groups, resources and API tokens; map each resource to an owner, environment and database account.
2. Turn on audit log streaming or collection first so changes are recorded.
3. Enable SSO with group sync for a pilot group, confirm admin recovery, then set DISABLE_USER_PASS_LOGIN.
4. Replace shared high-privilege resource accounts with dedicated least privilege accounts, one resource at a time, keeping the old credential disabled but recoverable until apps are tested.
5. Move secrets into secret configuration variables or an external manager and remove them from apps and queries.
6. On self-hosted, move ENCRYPTION_KEY and JWT_SECRET into your secrets manager, with a tested backup, before any key change.
7. Connect Source Control with branch protection and required checks, then stop direct edits on the production instance.

Common misconfigurations

• Owner-level database accounts behind resources: every app user inherits the ability to run any statement the account allows.
• Universal resource grants: convenient at launch, then every new production resource is open to the whole group.
• Secrets in app code: API keys pasted into queries or JavaScript are visible to editors and may reach the browser.
• Lost or unbacked-up ENCRYPTION_KEY: changing or losing it cuts off access to all existing resources, which turns a routine redeploy into an outage.
• Password login left on beside SSO: offboarding in the identity provider does not stop a user who still has a Retool password. See the Employee Offboarding Security Guide.
• Wide-scope API tokens: a Permissions write token kept in a CI variable is effectively a standing admin account.

Practitioner checklist

• Enable SSO with group sync and set DISABLE_USER_PASS_LOGIN once admin recovery is documented.
• Reduce the Admins group and replace direct user grants with delegated organisation roles.
• Remove Universal object role grants on production resources.
• Give every resource a dedicated, least privilege account per environment and a named owner.
• Move resource secrets into secret configuration variables or an external secrets manager.
• Store ENCRYPTION_KEY and JWT_SECRET in a secrets manager with tested backups, and set USE_GCM_ENCRYPTION.
• Scope Retool API tokens narrowly and review any holding Users, Groups or Permissions write.
• Stream audit logs to your SIEM and alert on admin changes and unusual query volumes.

Standards and references

• Retool: Role-based access control
• Retool: Manage configuration variables
• Retool: Security environment variables
• Retool: Authentication environment variables
• Retool: Configure Retool API authentication
• Retool: View user audit logs
• Retool: Source Control best practices
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Service Account Security Guide · Secrets Management Guide · Least Privilege Techniques Guide