Manage configuration variables

Learn how to create configuration variables and reference them across Retool.

Retool 4.34.2 Stable

Team • Business • Enterprise

You can specify configuration variables for reference in resource configurations, apps, and workflows. Configuration variables are specific to resource environments and can be either values or secrets.

Retool encrypts configuration variables on cloud instances or, if you self-host Retool, in your deployment's PostgreSQL storage database.

Requirements

Configuration variables are available to cloud instances and self-hosted instances using versions 3.4.0 and later for organizations on a Business or an Enterprise plan.

You must be an admin to create and edit configuration variables. Configuration variable values and secrets availability depends on usage. Only users with Edit permissions for a relevant area (e.g., resources) can use configuration variables.

Name	Values	Secrets	Description
Resources			Configuring resources in Retool can require handling sensitive values, e.g. database passwords or API keys. Retool is SOC 2 Type 2 compliant, and most customers store these values with Retool. Configuration variables allow you to centralize and control access to these values. If you have specific security requirements that require you to store secret values externally, rather than encrypted in Retool’s database, consider integrating Retool with a Secrets Manager.
Apps			Secret configuration variables are not available in apps and queries. You cannot use configuration variable values in public or external apps.
Workflows			As you build a workflow, Retool sanitizes secret configuration variables in block responses when running individual blocks. Secret values can only be passed to subsequent blocks when the workflow is run in its entirety, either by clicking Run workflow in the workflow IDE or when the workflow is triggered.

Create configuration variables

To create a configuration variable, go to Settings > Configuration variables.

Configuration variables have resource environment-specific values. For example, if you create a db_password configuration variable, you may need to specify different values depending on the resource environment (e.g., production or staging).

Default values

You can set a default value for a configuration variable that applies to all environments without an explicit value. This is useful when you want to:

• Use the same value across most environments and only override specific ones.
• Ensure all environments have a fallback value.

To set a default value, enter a value in the Default Value field when creating or editing a configuration variable. You can create a configuration variable with only a default value, or combine a default value with environment-specific values.

When an environment has both a default value and an environment-specific value configured, the environment-specific value takes precedence. Environments without their own explicit value display (using default value) as placeholder text.

On the main Configuration variables page:

• Variables with only a default value show All Environments in the Environment column.
• Variables with both a default value and environment-specific values show All Other Environments for the default value row.

Secret configuration variables

To create a secret, toggle Mark variable as secret when creating a configuration variable. Secret configuration variables are available for use only in resource configurations and workflows, and their values are never exposed on the frontend. Use secrets if you need to store sensitive information, such as security credentials.

Use configuration variables

You can use autocomplete to access configuration variables in the resource editor, app IDE, and workflow IDE. Retool uses the appropriate value depending on the current resource environment.

Reference configuration variables in resource configurations using the following syntax.

{{ environment.variables.YOUR_VAR_NAME }}

In apps, workflows, and queries:

{{ retoolContext.configVars.YOUR_VAR_NAME }}

Note

Configuration variables are cached so it may take up to five minutes for your changes to take effect.

Configuration variables with multi-instance deployments

Config vars are recommended for use with Protected Resources. When protecting a resource, only the template value ({{ environment.variables.your_name }}) is stored in Source Control. You must define your configuration variables on each instance.

Configuration variables, environment variables, and Secrets Managers

The use of configuration variables, RETOOL_EXPOSED variables, and Secrets Manager depends on your security and permission requirements.

Config vars are set directly in the Retool settings web interface, and are stored encrypted. Use configuration variables when you need to access variables per resource environment.

On self-hosted Retool instances, RETOOL_EXPOSED_* variables are set per-instance as environment variables. Their values are never exposed in Retool.

If your use case requires higher levels of security, integrating with a third-party Secrets Manager such as AWS or Vault is recommended.

Configuration variables API

Organizations on the Enterprise plan with a cloud instances or self-hosted instance on version 3.42 and later can use the Retool API to manage configuration variables.

Prerequisites

Configuration variable API endpoints require a resource environment ID. You must retrieve this ID before you can list, create, or update configuration variables.

To get the environment ID for your default environment, use GET /environments/default and note the id value from the response. If you use multiple resource environments and need a specific one, use GET /environments to list all environments and find the appropriate ID.

Common use cases

The following are common use cases when managing configuration variables via the API.

List configuration variables for an environment

To list configuration variables for an environment, use the following steps:

1. Retrieve the environment ID using GET /environments/default or GET /environments.
2. List configuration variables using GET /config_vars, passing the environment_id parameter.

Note

This endpoint is paginated — use the next_token parameter to retrieve additional results.

Update a configuration variable

To update a configuration variable, use the following steps:

1. Retrieve the environment ID using GET /environments/default or GET /environments.
2. List configuration variables using GET /config_vars with the environment_id to find the ID of the variable you want to update. The list endpoint does not support filtering, so you may need to paginate through results.
3. Update the variable using PUT /config_vars/{config_var_id} with both the variable ID and environment ID.