Configure scoped secret access for resources

Restrict secrets usage to specific resource folders using naming enforcement.

Secrets restriction Availability
Self-hosted Edge	Closed beta	Enterprise
Self-hosted Stable	Closed beta	Enterprise

Self-hosted Retool instances are available on an Enterprise plan only.

Secrets retrieved from a supported secrets manager, such as AWS Secrets Manager or HashiCorp Vault, are available for use across all resources in a space. In some cases, it may be necessary to restrict the availability of some secrets to specific resources.

Retool supports naming convention enforcement that restricts the availability of secrets to specific resource folders. When enabled, a scoped secret is only available to resources within the specified folder. This complements any folder access rules in use, allowing for even greater restriction to specific users.

Enable scoped secrets

An organization admin can enable scoped secrets by setting the SCOPED_SECRETS environment variable for the deployment.

SCOPED_SECRETS=true

Once enabled, Retool enforces scoped secrets naming for any secrets that start with scoped__.

Apply the naming convention for scoped secrets

You restrict secrets to specific resources by naming secrets according to the following convention:

Scoped secret naming convention

scoped__resources__<folder>__<secret>

Fragment	Description
scoped	Identifies the secret as scoped.
resources	The scoped secret applies to resources.
< folder >	The parent folder of the resource.
< secret >	The name of the secret.

Scoped secrets use double underscores to separate each fragment. This is to avoid unintentional conflicts with any existing secrets that may share a similar name but are not to be scoped. For example:

• scoped__resources__folder1__secret1: Retool restricts secret1 to resources within folder1.
• scoped__resources__folder2__secret2: Retool restricts secret2 to resources within folder2.
• scoped_resources_folder3_secret3: Retool does not restrict this secret as it does not follow the naming convention which requires double underscores for fragment separation.

Folder name considerations

Before creating a scoped secret, keep the following considerations in mind to ensure maximum compatibility:

• Retool supports the use of spaces and special characters in folder names. Secret managers do not allow spaces and certain special characters. You may need to rename a resource folder so it uses only valid characters.
• Secrets managers support the - character for secret names. Since Retool uses JavaScript when handling any {{ }} expressions, the - character is invalid. This does not affect the usage of a secret but it prevents autocomplete and syntax highlighting from functioning.

Retool recommends using simpler names and unambiguous characters to maximize compatibility.

Reference scoped secrets

You use scoped secrets in the same way as any other secret by using {{ }} expressions and the secret object:

Scoped secret reference

{{ secret.scoped__resources__folder1__secret1 }}

Retool autocompletes all available secrets as you type and lists all globally scoped secrets, along with any scoped secrets that may be available for the current resource folder.