Retool Spaces + HTTP versus HTTPS Callback Issue

🧑‍💻 Retool Tips & Tricks
1

Overview

In a self-hosted Retool Enterprise deployment, enabling multiple Spaces can cause OAuth callback URLs to switch from https:// to http:// if certain environment variables aren't set properly. This guide explains why that happens and how to configure your environment for secure HTTPS callbacks.

Key Takeaways

  • COOKIE_INSECURE must be false for HTTPS
  • When Retool is in multi-space mode and COOKIE_INSECURE=true, Retool generates HTTP callback URLs, even if TLS is otherwise configured.
  • For production HTTPS setups, always set COOKIE_INSECURE=false.
  • BASE_DOMAIN alone is not enough in Multi-Space.
  • In single-space mode, BASE_DOMAIN=https://example.com can be sufficient for secure callbacks.
  • In multi-space mode, Retool uses a combination of request headers and the COOKIE_INSECURE setting to determine whether the callback URL should be http:// or https://.

Why This Behavior Is Expected

  • Once Spaces are enabled, Retool no longer has a single canonical domain for all routes.
  • The code that determines the callback protocol explicitly checks if COOKIE_INSECURE is set to true.

How It Manifests

Symptoms:

Creating a new space results in Google callback URLs using http:// instead of https://.

Removing or disabling Spaces reverts the callback URLs to https://.

Root Cause:

Retool sees COOKIE_INSECURE=true and decides the environment is insecure, forcing http://.

In single-space mode, the presence of BASE_DOMAIN=https://... was overriding that, but in multi-space mode, Retool's logic shifts to using the COOKIE_INSECURE setting and the Host header for the protocol.

Recommended Configuration

  • Set COOKIE_INSECURE=false
  • If you're serving Retool over TLS (behind an HTTPS Ingress), make sure COOKIE_INSECURE is explicitly set to false.

Verify Other Environment Variables

  • BASE_DOMAIN: Should match your main domain with https://.

  • HOST_HEADER_NAME: Typically defaults to Host; only change if you have a specialized proxy setup.

  • Confirm you don't have conflicting environment variables referencing http://.

Confirm Headers

  • Ensure your Ingress sets X-Forwarded-Proto: https (if SSL is terminated at the load balancer).
  • Make sure the Host header is preserved for each subdomain (for example: *.yourcompany.com).

Single-Space vs. Multi-Space

  • If you aren't using multiple subdomains, setting BASE_DOMAIN to https://myretool.example.com can be enough for secure callbacks.
  • Once you enable Spaces (subdomains for each space), Retool relies on COOKIE_INSECURE=false to maintain HTTPS.

FAQs

Why did single-space mode work fine with COOKIE_INSECURE=true?

In single-space mode, BASE_DOMAIN=https://... may override the insecure setting. Multi-space logic explicitly checks COOKIE_INSECURE for protocol determination.

Is this a bug?

No, this is expected behavior. The multi-space SSO flow uses COOKIE_INSECURE to decide whether to generate http:// or https://.

What if I need local HTTP testing?

You can set COOKIE_INSECURE=true for non-production setups that don't use TLS. But in production or staging with TLS, keep it set to false.

1 Like