Learn how to use app auth tokens in each context
When working on VTEX IO apps, you generally don't make direct requests to VTEX APIs. This is because VTEX IO already provides convenient access to VTEX APIs through predefined clients. Therefore, using application keys within your app is often unnecessary. If you need to use them, the recommended approach is using authentication tokens.
We recommend using the VTEX IO clients package when possible. With this package, every client method has an optional argument called authMethod, which accepts one of three authentication options, each indicating which token to use for the request.
The tokens are available via the VTEX IO context and are associated with different permissions.
You can import the context in your app as follows: import { IOContext } as ctx from '@vtex/api'. See the table below to learn about each token.
| Token | authMethod | Via context | Description | Permissions |
|---|---|---|---|---|
| App authentication token (default) | AUTH_TOKEN | ctx.authToken | Every VTEX IO app has its own temporary authentication token. We recommend avoiding the use of this app token whenever user tokens are available. | Permissions declared in the policies defined in the app's manifest, where developers must declare precisely what actions are allowed for the app they are building. |
| Store user token | STORE_TOKEN | ctx.storeUserAuthToken | User token with store scope. | Shopper permissions. |
| Admin user token | ADMIN_TOKEN | ctx.adminUserAuthToken | User token with Admin scope. | Administrative permissions as defined by License Manager roles associated with the current logged-in user. |
If your project requires features not provided by the available clients, we recommend creating your own clients following the same authentication logic.
Authenticate app actions with user tokens whenever possible. Currently, app authentication tokens are not subject to License Manager permissions. We recommend considering this when defining app architecture and configuring policies.
Usage examples
Below are examples of how to use each token type in a client definition.
App authentication token
Use the app authToken when operations are not linked to a user. In this case, the permission level is defined by policies in the app manifest.json file.
_11export class OmsClient extends JanusClient {_11 constructor(ctx: IOContext, options?: InstanceOptions) {_11 super(ctx, {_11 ...options,_11 headers: {_11 ...options?.headers,_11 VtexIdclientAutCookie: ctx.authToken,_11 },_11 })_11 }_11}
Store user token
When the app is focused on store browsing experience, use storeUserAuthToken whenever possible. This way, app permissions will be limited to shopper user permissions in the account.
_11export class OmsClient extends JanusClient {_11 constructor(ctx: IOContext, options?: InstanceOptions) {_11 super(ctx, {_11 ...options,_11 headers: {_11 ...options?.headers,_11 VtexIdclientAutCookie: ctx.storeUserAuthToken,_11 },_11 })_11 }_11}
Admin user token
When the app is focused on Admin experience, use adminUserAuthToken whenever possible. This way, app permissions will be limited to Admin user permissions in the account.
_11export class OmsClient extends JanusClient {_11 constructor(ctx: IOContext, options?: InstanceOptions) {_11 super(ctx, {_11 ...options,_11 headers: {_11 ...options?.headers,_11 VtexIdclientAutCookie: ctx.adminUserAuthToken,_11 },_11 })_11 }_11}