Each API integration used to connect your VTEX account with external systems will require the creation of an application key, also known as an app key.

These authentication credentials are used to ensure secure access to the data you want to share with these integrations, without exposing your account to unauthorized users or applications.

There are two types of application keys: internal or external. This definition depends on which account creates, manages, and uses the credential.

Internal application keys are credentials generated in and managed by your VTEX account. This means you should have access to all pairs of application keys and tokens, which is akin to usernames and passwords for API integrations.

External application keys are credentials generated in and managed by other VTEX accounts. By adding roles to application keys — which are equivalent to usernames — provided by third parties, you can allow them to access specific resources in your account.

A role with the Save User resource is required to manage users and application keys. The default role for this purpose is User Administrator - RESTRICTED, but it is also possible to create a custom role with this resource.

On the Application Keys page, you can manage the internal and external app keys that have access to your account, including:

• Generate internal application keys
• Add external application keys
• Manage application key permissions
• Activate or deactivate application keys
• Export application keys with access to your account

To view this page, at the top bar of the VTEX Admin, click your profile avatar — indicated by the first letter of your email — and then click Account settings > Application Keys.

Learn more about best practices for using application keys.

As application keys allow external systems to access your account, they can only be created by users who have the License Manager / Services access control / Save user feature in their roles.

To create internal app keys in your account, follow the steps below:

1. At the top bar of the VTEX Admin, click your profile avatar — indicated by the first letter of your email — and then click Account settings > Application Keys.

2. Click the Manage My Keys button.

   You will be redirected to the My Keys page, as shown below. This page lists all internal app keys.

   

   These are the visible fields on the My Keys page:

   • Label: Text field describing the purpose of the app key.
   • Key: Unique identifier for the app key.
   • Status: Current status of the app key, which can be active or inactive.

3. Click the + Generate New button.

4. (Optional) Complete the Label with a description of the purpose of the app key. This field is set only when creating the app key and cannot be changed afterward. If left blank, it will default to the Key value of the generated app key.

5. (Optional) Click + Add Roles to manage application key permissions.

6. Click the Generate button.

7. Click to copy the Application token. This secret will only be displayed once. Save it in a safe place.

Secure your application keys and token pairs as you would with other credentials, such as usernames and passwords. If you suspect an application key is compromised, immediately deactivate the key in your account. To learn more, read the Activating or deactivating application keys section of this article.

To add third-party application keys, follow the steps below:

1. At the top bar of the VTEX Admin, click your profile avatar — indicated by the first letter of your email — and then click Account settings > Application Keys.
2. Click the + Add 3rd Party Key button.
3. Complete the Key field with the app key provided by the third party.
4. Click + Add Roles to manage application key permissions. Add roles to allow them to access the resources you desire.
5. Click Save.

For an application key to successfully make API requests to your account, it must both be active and have roles specifying the account resources it is allowed to access.

Unrestricted use of overly permissive roles increases the risk of store attacks through leaked login credentials.

Application keys are created, by default, with no permission to access any account resources.

There are three different paths to the page where you can edit the roles for an app key:

• Use the + Add Roles button to generate application keys in your account.
• Use the + Add 3rd Party Key button on the Application keys page.
• Use the ፧ button and select the Edit option on the Application Keys or My Keys pages.

When editing an application key, you can:

• Add roles by clicking the + Add Roles button, selecting one or more roles, and clicking the Add Roles button.
• Remove roles by selecting them using the checkboxes and then clicking the Remove Roles button.
• Save the changes by clicking the Save button.

Once you have added roles to an application key, it will be displayed on the Application Keys page.

These are the visible fields on the Application Keys page:

• Key: Unique identifier for the app key.
• Account: VTEX account managing the app key.
• Status: Current status of the app key, which can be active or inactive.

Note that the Label field is not displayed on the Application Keyspage. To see a description of the purpose of an internal app key, you will have to use theKey value to find it on the My Keys page. It is not possible to add labels to external app keys.

If an application key that has access to your account is compromised, you should immediately revoke its access to your account. If you make a mistake, you can reactivate it to reestablish the impacted integration. This can be done in various ways depending on the type of application key.

You should only reactivate an app key if you are certain it has not been compromised. Anyone with the associated app token will regain privileged access to your account.

To deactivate an internal app key, follow the steps below:

1. At the top bar of the VTEX Admin, click your profile avatar — indicated by the first letter of your email — and then click Account settings > Application Keys.
2. Click the Manage My Keys button.
3. Find the app key you want to deactivate in the list and click the ፧ button.
4. Click the Deactivate option.

To deactivate an external application key, follow the steps below:

1. At the top bar of the VTEX Admin, click your profile avatar — indicated by the first letter of your email — and then click Account settings > Application Keys.
2. Find the app key you want to deactivate in the list and click the ፧ button.
3. Click the Remove option.

To reactivate internal application keys that have previously been deactivated, follow the steps below:

1. At the top bar of the VTEX Admin, click your profile avatar — indicated by the first letter of your email — and then click Account settings > Application Keys.
2. Click the Manage My Keys button.
3. Find the app key you want to reactivate in the list and click the ፧ button.
4. Click the Activate option.

To reactivate external application keys that have previously been deactivated, you will need to follow the instructions again as described in the Adding external application keys section.

If necessary for a security audit, you can export a CSV file containing the Key values for all internal and external app keys that currently have access to your account — that is, that have roles associated with them.

To export the keys, go to Account settings > Application keys and click the Export button.