Managing Secrets
In this guide, you'll learn how to manage secrets in your FastStore project using WebOps.
Secrets are sensitive information, such as API keys, passwords, and tokens, that must be securely managed during the FastStore project deployment.
WebOps centralizes and standardizes secret management, providing a consistent and secure process across all deployment providers. This ensures that sensitive information is kept outside your project codebase and is retrieved securely by WebOps.
The secrets of stores that don't use WebOps are handled through the VTEX IO CLI secrets plugin. To enable secret management, you need to have an emptyvtex.envfile in the project root. The key-value pairs are stored in thesecrets.revealed.jsonfile, which is then encrypted intosecrets.hidden.jsonbefore being committed to the main branch. For stores using WebOps, this workflow has been deprecated, and secrets are managed directly through the WebOps interface.
Local development
For local development, you must use the
vtex.env file to define the secrets needed to run your FastStore project locally.The
vtex.env file is only used in local environments and should always be added to .gitignore to avoid leaking secrets through version control. By adding it to .gitignore, secrets defined in the vtex.env file won't be available in deployed environments via WebOps.Instructions
To manage your secrets, go to your FastStore WebOps dashboard and navigate to the Settings tab.
Creating secrets
-
In the
Keyfield, enter the name of the secret, which serves as its unique identifier (example: VTEX_API_TOKEN, NEXT_SECRET_KEY). In theValuefield, enter the corresponding sensitive information you want to store (example: the actual token, key, or password).Secrets accessible in the browser (client-side) must start with the prefixNEXT_PUBLIC_. Use names without this prefix for all other secrets. -
Click
Add. A pop-up withNew secret added successfullywill open, and you'll see the messageSecrets have changed. Changes will take effect in the next successful deployment.alongside aRedeploybutton.When creating multiple secrets, make sure you include all of them before proceeding to the next step. This prevents sync errors. -
Click
Redeployto redeploy your website with the updated secret configuration. You’ll see the messageRedeploying with secret changes, and a pop-up withDeployment created successfullywill open. -
Track the deployment status in the Deploys tab of the WebOps dashboard.
During the build process, any secrets added through WebOps will be transformed into environment variables within the code, which automatically loads them into the
process.env object. You can access these values in your code using process.env.VARIABLE_NAME. Remember to replace VARIABLE_NAME with the name you assigned to your secret in the Key field.The secret created will be available in the Current Keys section.
Updating secrets
- Go to the
Current Keyssection. - Next to the secret you need to update, click
⋮and then clickEdit. - Click
Update. A pop-up withSecret updated successfullywill open, and you'll see the messageSecrets have changed. Changes will take effect in the next successful deployment.alongside aRedeploybutton. - Click
Redeployto redeploy your website with the updated secret configuration. You’ll see the messageRedeploying with secret changes, and a pop-up withDeployment created successfullywill open. - Track the deployment status in the Deploys tab of the WebOps dashboard.
Deleting secrets
-
Go to the
Current Keyssection. -
Next to the secret you need to update, click
⋮and then clickDelete. -
Confirm the secret you want to remove.This action can’t be undone.
-
Click
Delete secret. A pop-up withSecret deleted successfullywill open, and you'll see the messageSecrets have changed. Changes will take effect in the next successful deployment.alongside aRedeploybutton. -
Click
Redeployto redeploy your website with the updated secret configuration. You’ll see the messageRedeploying with secret changes, and a pop-up withDeployment created successfullywill open. -
Track the deployment status in the Deploys tab of the WebOps dashboard.
If you tried to create, update, or delete a secret and got the errorFailed to create/update/delete secret. Please, try again., repeat the process. If the problem persists, open a ticket with VTEX support.