Skip to main content

Configure scoped secret access for resources and workflows

Restrict secrets usage to specific resource or workflow folders using naming enforcement.

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

Retool supports naming convention enforcement that restricts the availability of secrets to specific resource or workflow folders. When enabled, a scoped secret is only available to resources or workflows 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 resource or workflow folders by naming secrets according to the following convention:

Scoped secret naming convention
scoped__resources__<folder>__<secret>
FragmentDescription
scopedIdentifies the secret as scoped.
resourcesIdentifies the scope type. This fragment is always resources, even when the folder it names is a workflow folder rather than a resource folder.
< folder >The parent folder of the resource or workflow.
< 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 and workflows within folder1.
  • scoped__resources__folder2__secret2: Retool restricts secret2 to resources and workflows 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 or workflow 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.
Best practice

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 secrets object:

Scoped secret reference
{{ secrets.scoped__resources__folder1__secret1 }}

In workflow Code blocks and other non-resource blocks, reference the same secret through retoolContext.secrets instead:

Scoped secret reference in a workflow Code block
retoolContext.secrets.scoped__resources__folder1__secret1

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