API authentication using user tokens

When a user successfully logs in to a VTEX store, VTEX ID issues a JWT user token and stores it in an HTTP-only cookie. For Admin sessions, the cookie name is VtexIdclientAutCookie. For webstore (shopper) sessions, the cookie name is VtexIdclientAutCookie_{accountName} or VtexIdclientAutCookie_{accountId}.

For a period of 24 hours after its creation, the user token can be used to authenticate requests to VTEX APIs. Send it in an HTTP header as cookies whose name matches that cookie (same pattern as above, depending on audience).

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.

User tokens and associated permissions are tied to the user who logged in. Each request must use credentials valid for the VTEX account where that operation runs. The account in the API hostname must be the same as the account the token was issued for.

Developers working with VTEX can generate authentication tokens without having to simulate a shopper’s 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:

• Generating user tokens
  • Generating a user token with the VTEX IO CLI
  • Generating an authentication token with the VTEX ID API

1. Install the VTEX IO CLI.

2. Log in to VTEX by running the following command on your terminal. Remember to replace the {accountName} value with your VTEX account name.

   
   

   _10

   vtex login {accountName}

   
   

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

   
   

   _10

   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.

To do this, use the Generate authentication token endpoint.

Note that the token generated by this API endpoint is not tied to a user profile but to an API key, which means this token's permissions are the same as defined to the credential pair, instead of having the same permissions as the logged in user. Still, you can use this token to authenticate API requests in the same way as a regular user token, informing its value in the VtexIdclientAutCookie header.