In this article, you can learn about all authentication aspects relevant to developers building integrations with VTEX:

• Machine authentication
• Single Sign On integration
• Shopper authentication for B2B stores

️ See this related content:\n- Authorization: Users, Roles and License Manager Resources\n- Accounting: Audit

There are different contexts in which machine authentication is required in the regular functioning of a VTEX store. Because of that, there are different ways this is done. Below are some example use cases and details about machine authentication methods.

️ The authentication methods in the table above are indicated but are not the only alternative for these use cases. Learn more about each method and how to use them below.

Application keys (appKey) are credentials used to authenticate requests to VTEX APIs. Store administrators can create multiple application keys that may be used, for example, for different integrations.

You can manage permissions for any given application key with License Manager roles and resources.

Application keys are usually the best way to authenticate API calls in your integrations. However, there are some VETX API endpoints that do not allow this mode of authentication. Authenticate those with user tokens.

Do not use application keys in your client-side code. This makes your store vulnerable to attacks.

Below you can learn more about how to authenticate API requests in this way. Still, we recommend reading these other articles to develop secure API integrations:

• Generating and managing application keys
• Best practices for using application keys

Authenticating requests with application keys

Each appKey you create has an associated appToken. Use this credential pair to authenticate API requests by sending their values in these HTTP headers:

See an example Get order request:

curl --location --request GET 'https://apiexamples.vtexcommercebeta.com.br/api/oms/pvt/orders/:orderId' \
--header 'X-VTEX-API-AppKey: vtexappkey-example-YSWQFZ' \
--header 'X-VTEX-API-AppToken: eyJhbGciOiJFUzI1NiIsImtpZCI6IjA1MTZFN0IwMDNFODMxRTg0QkFDOTg2NzBCNUM2QTRERTlBN0RFNkUiLCJ0eXAiOiJqd3QifQ.eyJzdWIiOiJwZWRyby5jb3N0YUB2dGV4LmNvbS5iciIsImFjY291bnQiOiJhcHBsaWFuY2V0aGVtZSIsImF1ZGllbmNlIjoiYWRtaW4iLCJzZXNzIjoiZjU3YjMyMGItMWE3YS00YzlkLWJkNDMtZTE4NDdhYmE1MTE1IiwiZXhwIjoxNjE2NzY3Mjc4LCJ1c2VySWQiOiJmYjU0MmU1MS01NDg4LTRjMzQtOGQxNy1lZDhmY2Y1OTdhOTQiLCJpYXQiOjE2MwerY2ODA4NzgsImlzcyI6InRva2VuLWVtaXR0ZXIiLCJqdGkiOiJmYTI0YWJiOC03Y2E5LTQ3NjUtYmYzNC1kMmvU5YTgzYjYxZmUifQ.23rn-2dEdAAYXJX2exrxDEdbieyKWsVKABeSUNeFWyhz7xRd7d5EcxwiMLjM3bRaBOKrAA9Op7ocn89c45qQ' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

️ 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.

Whenever a user successfully logs in to your VTEX store, VTEX ID generates a JWT user token and sets it as the VtexIdclientAutCookie cookie.

For a period of 24 hours after its creation, the user token can be used to authenticate requests to VTEX APIs. To do this, send it as a header named VtexIdclientAutCookie.

User tokens allow for actions limited to their scope, which is defined according to the user who logged in:

• Shopper - Shoppers' tokens have permission to perform actions related to the shopping experience, such as viewing active products' information, placing orders, and viewing information of orders made under that same shopper profile. This token scope does not allow users to access the VTEX Admin panel or change logistics settings, for example.
• Admin - Administrative users' tokens allow for actions based on License Manager roles attributed to them. This may include access to different Admin panel pages or the ability to edit different configurations, for example.

As described above, user tokens and associated permissions are tied to the user who logged in. However, they are not store-exclusive. This means, for example, that administrative users with access to different accounts can perform actions in all of those stores with the same token.

Developers working with VTEX may generate authentication tokens without having to simulate login. This can be useful to run tests or even to generate tokens programmatically if your integration depends on an API that can not be authenticated with application keys. There are two methods you can use:

• VTEX IO CLI
• VTEX ID API

Generating tokens with the VTEX IO CLI

1. Make sure you have the VTEX IO CLI installed.
2. Log in to VTEX by running this command on your terminal:

   vtex login {accountName}
   

3. Once you are logged in to your VTEX account, run this command:

   vtex local token
   

With this, the CLI will generate a valid user token associated with your profile print it to your terminal and also copy it to your clipboard.

Generating tokens with the VTEX ID API

To do this, use the Generate authentication token endpoint.

Note that the token generated by this API endpoint is not actually a user token since it is not tied to a user profile but to an application key. This token's permissions are the same as defined to the credential pair. However, you can use this token to authenticate API requests in the same way as a user token: as the VtexIdclientAutCookie header.

In general, when developing VTEX IO apps, you will not need to send requests to VTEX APIs because these platform features are available through clients. Hence, you will most likely not need to use application keys in your app.

Authenticating VTEX IO client operations

We recommend using the VTEX IO clients package when possible. In this context, every client method accepts an optional argument called authMethod, which receives one of three authentication options, indicating which token will be used in this request:

If your project requires features not provided by these, it is a good idea to create your own clients following the same authentication logic. The tokens shown above are available via the VTEX IO context and are associated with different permissions. See the table below to learn about each token. ℹ️️ You can import the context in your app like this:\nts\nimport { IOContext } as ctx from '@vtex/api'\n

Authenticate your apps' actions with user tokens whenever possible. Currently, app authentication tokens are not subject to License Manager permissions. We recommend that you consider this when defining your app's architecture and configuring policies.

VTEX allows stores to integrate with external identity providers to provide single sign on (SSO) experiences to shoppers and Administrative users. You can learn more about this in the article Login (SSO) and below you can find more information on these and other SSO use cases:

• Store SSO with OAuth 2.0
• Admin SSO with SAML 2.0
• Use your VTEX account as an OAuth provider
• Unifying login for different accounts

VTEX stores have access to different B2B solutions. See the articles below to learn more about authentication in the context of these different solutions:

• B2B Suite - Storefront permissions
• Legacy B2B solution - Configuring a B2B environment