VTEX Developer Portal

Authentication

Learn how to get authorization to access VTEX REST APIs.

VTEX offers a series of open APIs so that retailers and partners can make highly customizable integrations with our systems.

Most of these APIs are private and, as so, require you to provide a pair of credentials before you can access them.

These credentials are:

  • An appKey
  • An appToken

They work as a pair of ID and password, and must be created inside your store's administration panel.

🚧

Only the Master user of the store has permission to create and manage appKeys and appTokens. The Master user is the one whose email is in the Contact section of the Accounts screen, in Account Management.

Creating the appKey and appToken

To create a pair of credentials, the Master user should follow these steps:

  1. In the Admin's side menu, click on Account Management and then on Accounts.
  2. Type your account name in the Search bar and then hit the Enter button.

📘

The account name is your business identification on VTEX system. It's the one you use inside the URL that gives access to your admin: accountName.myvtex.com

  1. Click on your account name. You'll be redirected to the account configuration page.
  2. In the Security section, click on Generate appKey and appToken.
  3. Enter a label for the appKey and appToken pair you're creating.
  4. Click on Generate new Tokens.
  5. The token is in the field that is shown next.
VTEX credentials creationVTEX credentials creation

VTEX credentials creation

🚧

For a matter of safety, the appToken is only shown once after you create it. Copy this token and save it in a safe place.

Choosing a role for the credentials

Every appKey and appToken pair, once created, is born without any link to a role. So, after creating it, you should make this link, in order to define the permissions granted for these credentials.

To do that, follow these steps:

  1. Still in the Security section, inside the Accounts tab, copy the appKey, which is located in the Access key column.
  2. Back in the Account Management admin section, enter the Users tab and search for the key you've just copied.
  3. Click on the user name and choose the roles you want it to have. This appKey will only be able to authenticate integrations with the modules and features to which the chosen role gives access.

Using the appKey and appToken to authenticate

Now it's time to authenticate your first integration with a VTEX API.

You will do it by using the appKey and appToken you've just created as values of your request's authentication headers.

  1. In the first header, enter X-VTEX-API-AppKey as key. The value of this header must be the appKey created in the admin.
  2. In the second header, enter X-VTEX-API-AppToken as key. The value of this header must be the appToken created in the admin.

📘

According to the W3C definition of Message Headers in HTTP requests, header names are case-insensitive. X-VTEX-API-AppKey, x-vtex-api-appkey or any other variation in the authentication headers will work the same way.

Great job! You should now be able to authenticate and use VTEX APIs on your account.

Let's do that in the next step of this introduction.

Updated about a month ago



Authentication


Learn how to get authorization to access VTEX REST APIs.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.