[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides vtex io documentation 2 basicsetuptodevelopinvtexio in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-getting-started)

[Storefront apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-1-developing-storefront-apps-using-react-and-vtex-io)

[Pixel apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-1-developnativeintegrationswithpixelapps)

[What is a Pixel app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-pixel-app)

[1\. Setting up your development environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio)

[2\. Cloning the boilerplate repository](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-3-cloningtheboilerplaterepository)

[3\. Configuring your app settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-4-configuringyourappsettings)

[4\. Writing the head and body scripts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-5-writingtheheaderandbodyscripts)

[5\. Listening to store events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-6-listeningtostoreevents)

[6\. Structuring the documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-7-structuringthedocumentation)

[7\. Making your Pixel app publicly available](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-8-makingyourpixelapppubliclyavailable)

[Master Data CRUD](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/create-master-data-crud-app)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-getting-started)

[Storefront apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-1-developing-storefront-apps-using-react-and-vtex-io)

[Pixel apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-1-developnativeintegrationswithpixelapps)

[What is a Pixel app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-pixel-app)

[1\. Setting up your development environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio)

[2\. Cloning the boilerplate repository](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-3-cloningtheboilerplaterepository)

[3\. Configuring your app settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-4-configuringyourappsettings)

[4\. Writing the head and body scripts](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-5-writingtheheaderandbodyscripts)

[5\. Listening to store events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-6-listeningtostoreevents)

[6\. Structuring the documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-7-structuringthedocumentation)

[7\. Making your Pixel app publicly available](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-8-makingyourpixelapppubliclyavailable)

[Master Data CRUD](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/create-master-data-crud-app)

---

Project structure

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/app-development)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-getting-started)

[Pixel apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-1-developnativeintegrationswithpixelapps)

[1\. Setting up your development environment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio)

Setting up your development environment

In this part of the tutorial, you will:

* Install all the necessary tools to develop your own Pixel app.
* Create a new development workspace.
* Access your store using a workspace.

## Instructions

### Step 1 - Installing the VTEX IO CLI

Any development in VTEX IO begins and ends with the **VTEX IO CLI**, which works as a communication gateway between your store and the VTEX IO development platform. With VTEX IO’s CLI, you can use the terminal to log in to your VTEX account, manage workspaces, develop apps, and install new ones.

1. Install the VTEX IO CLI on your machine by following [this guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-install).
2. Check if the installation was successful by running `vtex`.

### Step 2 - Logging in to your VTEX account

After installing the VTEX IO CLI in your machine, take the following steps to log in to your VTEX account.

1. Log in to your VTEX account by running the following command:

`1

vtex login accountName

`

> Replace `accountName` with the name of your VTEX account.

![{"base64":"  ","img":{"width":1462,"height":360,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":183987,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-2-basicsetuptodevelopinvtexio-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-2-basicsetuptodevelopinvtexio-0.png)

1. After running the command, a browser window will open and ask for your credentials. Please enter the information required to log in to your account successfully.

### Step 2 - Creating a development workspace

When developing with VTEX IO, you'll use different [**workspaces**](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-workspace/). Workspaces are environments isolated from one another. They can be understood as different versions of the same VTEX account. In practice, changes performed in a particular workspace do not affect your store's live version or other developers' work.

When you log in to a VTEX account using the VTEX IO CLI, you are automatically in the **master** workspace, which is the version of your store available to end-users. Hence, to avoid changing your store's live version, you must create a **development workspace**.

1. Create a development workspace by running the following command:

`1

vtex use exampleworkspace

`

> Replace `exampleworkspace` with a name of your choosing to identify your new workspace.

1. Enter `Y` to create the new workspace.

![{"base64":"  ","img":{"width":652,"height":154,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":53203,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-2-basicsetuptodevelopinvtexio-1.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-2-basicsetuptodevelopinvtexio-1.png)

After running this command, you'll be taken to the `exampleworkspace` workspace, and all your operations will now run in this specified workspace.

### Step 3 - Accessing your store using a workspace

After creating a new development workspace, you can access this version of your store by going to: `https://exampleworkspace--accountName.myvtex.com`, where:

* `exampleworkspace` \- Name of the workspace that you've just created.
* `accountName` \- Name of the VTEX account in which you are working.

Done! You're now ready to start developing your Pixel app!

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Getting-Started/vtex-io-documentation-1-developnativeintegrationswithpixelapps/vtex-io-documentation-2-basicsetuptodevelopinvtexio.md)

[What is a Pixel app« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio//docs/guides/vtex-io-documentation-pixel-app)[2\. Cloning the boilerplate repositoryNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio//docs/guides/vtex-io-documentation-3-cloningtheboilerplaterepository)

See also

[2\. Cloning the boilerplate repositoryApp Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-3-cloningtheboilerplaterepository)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23instructions)

[Step 1 - Installing the VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-1-installing-the-vtex-io-cli)[Step 2 - Logging in to your VTEX account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-2-logging-in-to-your-vtex-account)[Step 2 - Creating a development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-2-creating-a-development-workspace)[Step 3 - Accessing your store using a workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-3-accessing-your-store-using-a-workspace)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Getting-Started/vtex-io-documentation-1-developnativeintegrationswithpixelapps/vtex-io-documentation-2-basicsetuptodevelopinvtexio.md)

Copy page

On this page

ON THIS PAGE

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23instructions)

[Step 1 - Installing the VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-1-installing-the-vtex-io-cli)[Step 2 - Logging in to your VTEX account](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-2-logging-in-to-your-vtex-account)[Step 2 - Creating a development workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-2-creating-a-development-workspace)[Step 3 - Accessing your store using a workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio/docs/guides/vtex-io-documentation-2-basicsetuptodevelopinvtexio%23step-3-accessing-your-store-using-a-workspace)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides faststore webops managing secrets in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/getting-started-faststore-versions-and-support-levels)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-dashboard)

[Configuring production and preview branches in WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-configuring-production-and-preview-branches)

[Managing Secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets)

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/headless-cms-overview)

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/storefront-best-practices)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/updates/release-notes)

Storefront Development

[Getting started with storefront solutions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/getting-started-with-storefront-solutions)

---

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore)

[FastStore versions and support levels](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/getting-started-faststore-versions-and-support-levels)

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/getting-started-overview)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-dashboard)

[Configuring production and preview branches in WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-configuring-production-and-preview-branches)

[Managing Secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets)

[Headless CMS](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/headless-cms-overview)

[Developer tools and references](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/developer-tools-overview)

[Styling](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/styling-overview)

[UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/components-index)

[Implementing storefront features](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/storefront-features-overview)

[FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/faststore-api-overview)

[FastStore SDK](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/sdk-overview)

[Developing and overriding UI components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/developing-and-overriding-components-overview)

[Extending the FastStore API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/api-extensions-overview)

[Managing URLs with redirects and rewrite paths](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/routing-managing-urls-with-redirects-and-rewrite-paths)

[Managing performance](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/managing-performance-overview)

[SEO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/seo-overview)

[Going live](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/go-live-overview)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/troubleshooting-overview)

---

[Store Framework](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/store-framework)

---

(Legacy) CMS Portal

---

[Storefront best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/storefront-best-practices)

---

[Storefront development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/storefront-development)

[FastStore](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore)

[FastStore WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-dashboard)

Managing Secrets

In this guide, you'll learn how to manage secrets in your FastStore project using [WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-2-starting-the-project).

Secrets are sensitive information, such as API keys, passwords, and tokens, that must be securely managed during the FastStore project deployment.

[WebOps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/getting-started-2-starting-the-project) 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](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-plugins) secrets plugin. To enable secret management, you need to have an empty `vtex.env` file in the project root. The key-value pairs are stored in the `secrets.revealed.json` file, which is then encrypted into `secrets.hidden.json` before 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.

## Before you begin

VTEX offers a permissions system, so only users assigned to a role with the required [License Manager resources](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) can manage secrets.

> The permissions system is in Open Beta. To enable it, open a ticket with [VTEX Support](https://read.calvincode.net/reader?url=https://help.vtex.com/en/support).

After enabling the feature, make sure you have a user associated with a role that contains the following License Manager resources:

* **Product:** FastStore
* **Category:** Secrets
* **Resources:** _View Secrets_ and _Edit Secrets_

![{"base64":"  ","img":{"width":1400,"height":616,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":29953,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/resources-secrets___02a8de499a7d29e3a94002e0dd016174.png"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/resources-secrets___02a8de499a7d29e3a94002e0dd016174.png)

## Instructions

To manage your secrets, go to your [FastStore WebOps dashboard](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/1-onboarding-dashboard) and navigate to the **Settings** tab.

![{"base64":"  ","img":{"width":1558,"height":750,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":1229954,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/secrets-settings-webops___c4cc35670f1faf9ecabd30447d1ee9b6.gif"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/secrets-settings-webops___c4cc35670f1faf9ecabd30447d1ee9b6.gif)

In the [Secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/1-onboarding-dashboard%23secrets) section, you can [create](#creating-secrets), [update](#updating-secrets), or [delete](#deleting-secrets) secrets following the steps below.

> After you create, update, or delete a secret, it may take a few minutes for the change to propagate. Wait 5 minutes before triggering a new deployment.
>
> If you deployed your storefront immediately after creating, updating, or deleting a secret and the change isn’t reflected in your store, wait a few minutes and run another deploy before opening a support ticket.

### Creating secrets

1. In the `Key` field, enter the name of the secret, which serves as its unique identifier (example: VTEX\_API\_TOKEN, NEXT\_SECRET\_KEY). In the `Value` field, 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 prefix `NEXT_PUBLIC_`. Use names without this prefix for all other secrets.
2. Click `Add`. A pop-up with `New secret added successfully` will open, and you'll see the message `Secrets have changed. Changes will take effect in the next successful deployment.` alongside a `Redeploy` button.
> When creating multiple secrets, make sure you include all of them before proceeding to the next step. This prevents sync errors.
3. Wait **5 minutes**, then click `Redeploy` to redeploy your website with the updated secret configuration. You'll see the message `Redeploying with secret changes`, and a pop-up with `Deployment created successfully` will open.
4. Track the deployment status in the [Deploys](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/1-onboarding-dashboard%23deploys) 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 `VARIABLENAME` with the name you assigned to your secret in the `Key` field_.

The secret created will be available in the **Current Keys** section.

![{"base64":"  ","img":{"width":1262,"height":726,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":397741,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/creating-secrets___14633df5e1e1385934d7f0854f00d340.gif"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/creating-secrets___14633df5e1e1385934d7f0854f00d340.gif)

### Updating secrets

1. Go to the `Current Keys` section.
2. Next to the secret you need to update, click `⋮` and then click `Edit`.
3. Click `Update`. A pop-up with `Secret updated successfully` will open, and you'll see the message `Secrets have changed. Changes will take effect in the next successful deployment.` alongside a `Redeploy` button.
4. Wait **5 minutes**, then click `Redeploy` to redeploy your website with the updated secret configuration. You'll see the message `Redeploying with secret changes`, and a pop-up with `Deployment created successfully` will open.
5. Track the deployment status in the [Deploys](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/1-onboarding-dashboard%23deploys) tab of the WebOps dashboard.

![{"base64":"  ","img":{"width":1262,"height":726,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":469565,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/updating-secrets___41a012c6f441bf927d67a59448c19894.gif"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/updating-secrets___41a012c6f441bf927d67a59448c19894.gif)

### Deleting secrets

1. Go to the `Current Keys` section.
2. Next to the secret you need to delete, click `⋮` and then click `Delete`.
3. Confirm the secret you want to remove.
> This action can't be undone.
4. Click `Delete secret`. A pop-up with `Secret deleted successfully` will open, and you'll see the message `Secrets have changed. Changes will take effect in the next successful deployment.` alongside a `Redeploy` button.
5. Wait **5 minutes**, then click `Redeploy` to redeploy your website with the updated secret configuration. You'll see the message `Redeploying with secret changes`, and a pop-up with `Deployment created successfully` will open.
6. Track the deployment status in the [Deploys](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/1-onboarding-dashboard%23deploys) tab of the WebOps dashboard.
![{"base64":"  ","img":{"width":1262,"height":726,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":337087,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/deleting-secrets___c5b464f532114c9895ce49af2fd8c76b.gif"}}](https://read.calvincode.net/reader?url=https://vtexhelp.vtexassets.com/assets/docs/src/deleting-secrets___c5b464f532114c9895ce49af2fd8c76b.gif)
> If you tried to create, update, or delete a secret and got the error `Failed to create/update/delete secret. Please, try again.`, repeat the process. If the problem persists, open a ticket with [VTEX support](https://read.calvincode.net/reader?url=https://help.vtex.com/en/support).

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/docs/getting-started/webops/managing-secrets.mdx)

[Configuring production and preview branches in WebOps« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-configuring-production-and-preview-branches)[Headless CMSNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/headless-cms-overview)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F112641072%3Fv%3D4%26w=64%26q=75)](https://github.com/barbara-celi)

ON THIS PAGE

[Local development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23local-development)

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23instructions)

[Creating secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23creating-secrets)[Updating secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23updating-secrets)[Deleting secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23deleting-secrets)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/faststore/docs/getting-started/webops/managing-secrets.mdx)

Copy page

On this page

ON THIS PAGE

[Local development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23local-development)

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23before-you-begin)

[Instructions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23instructions)

[Creating secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23creating-secrets)[Updating secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23updating-secrets)[Deleting secrets](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/faststore/webops-managing-secrets/docs/guides/faststore/webops-managing-secrets%23deleting-secrets)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides vtex storefront permissions in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/updates/release-notes)

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/updates/release-notes)

Storefront Permissions

> The **Storefront Permissions** app is part of VTEX’s [B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-b2b-suite) solution, which is a collection of apps that allow stores to manage organizations, storefront roles and permissions, and checkout settings for B2B commerce relationships. We recommend that you use it alongside the other apps in this suite for all functionalities to work as expected.

When navigating a B2B store as a customer, it is common for a main user from an organization to have other people under their structure, each with their own information and access privileges.

Within an organization, each user can have different roles, such as a professional buyer that places orders with budget limits from a predefined cost center or a manager in charge of reviewing and approving orders. These roles can be associated with multiple permissions, depending on the actions this user needs to perform.

The **Storefront Permissions** app stores a predefined set of roles and app permissions related to what B2B users can access and do in your storefront, making this information available for other integrated apps to check. This is useful for stores who want to set specific app permissions for users with different roles in an organization.

## Available storefront roles

In the following table, you can see the available storefront roles, their key used for identification in the app’s code, and their description.

| **Role**              | **Key**              | **Description**                                                                                |
| --------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Store Admin           | store-admin          | Store administrator, that is, a user who has access to the VTEX Admin.                                                                                |
| Sales Admin           | sales-admin          | Sales administrator user who can manage all sales users.                                                                                |
| Sales Manager         | sales-manager        | Sales manager user who can manage sales users in the same organization, as well as assist or impersonate buyers during navigation or purchase.                              |
| Sales Representative  | sales-representative | Sales representative user who can assist or impersonate buyers in the same cost center during navigation or purchase.                                                       |
| Organization Admin    | customer-admin       | Main organization user who manages the organization information, as well as its members and cost centers.                                                                   |
| Organization Approver | customer-approver    | Organization user who can take a saved cart or quote that was created by an **Organization Buyer** and use it to place an order.                                            |
| Organization Buyer    | customer-buyer       | Organization user who has the ability to add items to cart. If the **B2B Quotes** app is installed, they are also able to save their cart for future use or create a quote. |

## How it works

**Storefront Permissions** communicates automatically with other [B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-b2b-suite) apps, such as [B2B Organizations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-b2b-organizations), where it enables different organization management capabilities depending on each user’s role.

It also allows you to configure available permissions when developing your own app, associate them with the predefined roles, and have these permissions checked by other applications – if you perform the steps described in the [Advanced app integration](#advanced-app-integration-optional) section.

The **Storefront Permissions** app does not contain an interface – it operates “backstage”, storing the predefined roles and serving as a bridge to communicate with other apps in order to check user permissions. If you would like to manage roles and app permissions using the VTEX Admin interface, you must also install the [Storefront Permissions UI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions-ui) app. As an optional feature, you can install the [Admin Customers](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-admin-customers) app for additional customer management capabilities.

## Before you begin

Make sure you have the [VTEX IO CLI (Command Line Interface)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-install) installed in your machine.

If you opt to develop your own app and [integrate](#advanced-app-integration-optional) it with **Storefront Permissions**, read our documentation on [Developing an app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-developing-an-app).

## Installation

You can install the app by running `vtex install vtex.storefront-permissions` in your terminal, using the [VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference).

## Advanced app integration \[optional\]

If you would like to develop your own app and integrate it with **Storefront Permissions**, follow the steps below.

1. Open your app’s repository.
2. In the `manifest.json` file, add `vtex.storefront-permissions` under the `builders` property, as follows.
`1
"builders": {
2
"vtex.storefront-permissions": "1.x"
3
}
`
3. In the root folder, create a new folder named `vtex.storefront-permissions`.
4. In the `vtex.storefront-permissions` folder, create a `configuration.json` file. The content of this file should follow the format below. Keep in mind that you must replace the example information with the `name` of your app and its `features`.
`1
{
2
 "name": "My awesome app",
3
 "features": [
4
 {
5
 "label": "View",
6
 "value": "view-awesome-things",
7
 "roles": ["store-admin","sales-admin","sales-manager","sales-representative","customer-admin","customer-approver","customer-buyer"]
8
 },
9
 {
10
 "label": "Create",
11
 "value": "create-awesome-things",
12
 "roles": ["store-admin","sales-admin","sales-manager","sales-representative"]
13
 },
14
 {
15
 "label": "Delete",
16
 "value": "delete-awesome-things",
17
 "roles": ["store-admin","sales-admin","sales-manager","sales-representative"]
18
 },
19
 {
20
 "label": "Special Access",
21
 "value": "allow-special-access",
22
 "roles": ["store-admin","sales-admin"]
23
 }
24
 ]
25
}
`
Below you can find a description of each property.
| **Property** | **Type**         | **Description**                                                                                |
| ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name         | string           | Name of your app.                                                                                |
| features     | array of objects | List of features related to your app – the functionalities of your app that you want to set permissions for users to be able to access or not.                                                                                |
| ⤷            | object           | Object containing information about each feature of your app.                                                                                |
| ⤷ label      | string           | Name or description of the feature.                                                                                |
| ⤷ value      | string           | Identifier key you want to use for the feature, as used in your app’s [custom storefront components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-developing-custom-storefront-components). Do not use space or special characters in this field.      |
| ⤷ roles      | array of strings | List with the keys for all the roles you want to associate with the permission to use the feature by default. You can find more information about each role and its key in the [Available Storefront Roles section](#available-storefront-roles) of this documentation. |
5. Make sure you refer to the `value` – the identifier key – for each feature you want to set permissions for in your [custom storefront components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-developing-custom-storefront-components)’ code, when developing your app.
Example: in the B2B Organizations app, one of the permissions created is represented by the following object.
`1
{
2
 "label": "Create Cost Center",
3
 "value": "create-cost-center-organization",
4
 "roles": ["store-admin","sales-admin","customer-admin"]
5
}
`
Therefore, in a [custom storefront component’s code](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/b2b-organizations/blob/366a28add226eac5d9b104bb13a9f2cd1d574f02/react/components/CostCenterDetails.tsx) in TypeScript, whenever referring to this feature, it uses `create-cost-center-organization`.

Once you are done developing and installing your own app, if you have [Storefront Permissions UI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions-ui), the features of your app associated with each role will be automatically loaded on the **Storefront Permissions** page. For more details on this, read our documentation on the [Storefront Permissions UI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions-ui) app.

### GraphQL queries

Now that your app is integrated, you can write a GraphQL query on your app to check the current user's permission within the context of your app.

First, you need to associate your test user to a Role containing your app's permission by following the [B2B Organizations documentation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-b2b-organizations%23users).

It is not necessary to declare your app name nor user credentials, the query will take care of these details.

#### checkUserPermission

This query allows you to check which permissions a user has in the context of your app. When the query is performed, **Storefront Permissions** checks which app the request is coming from, and returns the current user's permissions for that specific app.

The response will be a list with all the permissions the current user has on the app.

Sample query:

`1

query permissions {

2

 checkUserPermission @context(provider: "vtex.storefront-permissions") {

3

 role {

4

 id

5

 name

6

 slug

7

 }

8

 permissions

9

 }

10

}

`

Sample response:

`1

{

2

 "data":{

3

 "checkUserPermission": {

4

 "role": {

5

 "id": "00549c22-f39d-11eb-82ac-0a55b612700f",

6

 "name": "Admin",

7

 "slug": "customer-admin"

8

 },

9

 "permissions": ["view-awesome-things","create-awesome-things","delete-awesome-things"]

10

 }

11

 }

12

}

`

#### hasUsers

This query allows you to check if there are any users associated with a specific role. The response will be a boolean, with `"hasUsers": true` if there are users with this role or `false` if there are not.

Sample query:

`1

query hasUsers {

2

 hasUsers(slug: "sales-admin")

3

 @context(provider: "vtex.storefront-permissions")

4

}

`

Sample response:

`1

{

2

 "data": {

3

 "hasUsers": true

4

 }

5

}

`

#### checkImpersonation

This query allows you to check if the current user is [impersonating](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-b2b-organizations%23impersonate-users) another user, and retrieve information on the impersonated user.

Sample query:

`1

query checkImpersonation {

2

 checkImpersonation {

3

 firstName

4

 lastName

5

 email

6

 userId

7

 error

8

 }

9

}

`

Sample response:

`1

{

2

 "data": {

3

 "checkImpersonation": {

4

 "firstName": "Andrew",

5

 "lastName": "Smith",

6

 "email": "testemail@mail.com",

7

 "userId": "aaaaa-bbbb-cccc-dddd-eeeee",

8

 "error": null

9

 }

10

 }

11

}

`

#### getSessionWatcher

Using Session Watcher, **Storefront Permissions** detects changes to the user authentication to trigger changes to its cart and navigation, based on associated price tables, collections, profile information and shipping options.

This query fetches Session Watcher’s status, that is, whether it is active or not. The response will be a boolean, with `true` meaning that it is enabled or `false` meaning it is disabled.

Sample query:

`1

query getSessionWatcher {

2

 getSessionWatcher

3

}

`

Sample response:

`1

{

2

 "data": {

3

 "getSessionWatcher": false

4

 }

5

}

`

### GraphQL mutation

#### impersonateUser

Using this mutation, you can inform the `userId` to [impersonate an user](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-b2b-organizations%23impersonate-users). To remove impersonation, send an empty `userId` instead.

Sample mutation:

`1

mutation impersonateUser($userId: ID)

2

@context(provider: "vtex.storefront-permissions") {

3

 impersonateUser(userId: $userId) {

4

 status

5

 message

6

 }

7

}

`

#### setSessionWatcher

If your account is not using `vtex.b2b-organizations` you may want to disable the Session Watcher to avoid unnecessary operations. To do so, set the `active` property to `false` in the mutation exemplified below.

The response will be a boolean, with `true` for a successful operation or `false` for a failure.

Sample mutation:

`1

mutation setSessionWatcher {

2

 sessionWatcher(active: false)

3

}

`

Sample response:

`1

{

2

 "data": {

3

 "sessionWatcher": true

4

 }

5

}

`

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Store-Framework-Apps/vtex-b2b-suite/vtex-storefront-permissions.md)

Contributors

1

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

ON THIS PAGE

[Available storefront roles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23available-storefront-roles)

[How it works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23how-it-works)

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23before-you-begin)

[Installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23installation)

[Advanced app integration \[optional\]](https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions#advanced-app-integration-optional)

[GraphQL queries](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23graphql-queries)[GraphQL mutation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23graphql-mutation)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Store-Framework-Apps/vtex-b2b-suite/vtex-storefront-permissions.md)

Copy page

On this page

ON THIS PAGE

[Available storefront roles](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23available-storefront-roles)

[How it works](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23how-it-works)

[Before you begin](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23before-you-begin)

[Installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23installation)

[Advanced app integration \[optional\]](https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions#advanced-app-integration-optional)

[GraphQL queries](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23graphql-queries)[GraphQL mutation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-storefront-permissions/docs/guides/vtex-storefront-permissions%23graphql-mutation)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)