2. Discovering VTEX Commerce APIs and authentication

Services Calling commerce APIs on VTEX IO

Now that we have a comprehensive understanding of the project structure, it's important to address API authentication before we proceed with calling VTEX Core Commerce APIs. VTEX strongly advises against using the AppKey and AppToken pair in VTEX IO apps. Instead, the recommended practice involves utilizing the VTEX ID token.

Every app developed on VTEX IO represents a resource on the platform. This allows an app to interact with other systems on behalf of itself, duly authorized by the account administrator. It is the reponsibility of the app developer to declare the necessary permissions. In practical terms, this entails:

Declaring both the endpoint and the roles required to access any API in the apps's manifest.json file.
Making request with a VTEX ID token instead of the AppKey and AppToken pair. For more information, refer to App authentication using auth tokens.

Logging the app token

Each VTEX IO app is issued a corresponding authToken. This token can be obtained from the ctx object and contains all the permissions declared in the policies field of the app's manifest.json file.

To inspect the authToken of an app, go to the node/middlewares/validate.ts file and add the highlighted log code.

node/middlewares/validate.ts


_24import { UserInputError } from '@vtex/api'
_24
_24export async function validate(ctx: Context, next: () => Promise<any>) {
_24  const {
_24    vtex: {
_24      route: { params },
_24    },
_24  } = ctx
_24
_24  console.log(ctx.vtex.authToken)
_24  console.info('Received params:', params)
_24
_24  const { code } = params
_24
_24  if (!code) {
_24    throw new UserInputError('Code is required') // Wrapper for a Bad Request (400) HTTP Error. Check others in https://github.com/vtex/node-vtex-api/blob/fd6139349de4e68825b1074f1959dd8d0c8f4d5b/src/errors/index.ts
_24  }
_24
_24  const codeNumber = parseInt(code as string, 10)
_24
_24  ctx.state.code = codeNumber
_24
_24  await next()
_24}

Checking the app token

With the app linked to your development workspace, access the service route and check the content logged in the terminal. Use the following URL format: https://{workspace}-{account}.myvtex.com/_v/status/:code, replacing {workspace} and {account} according to your scenario, and :code with 200

node/middlewares/validate.ts

Terminal


_10info: eyJhbGciOiJSUzI1NiIsImtpZCI6IkVFQkFGRjY1QkVFRUNDODUxQkQ2NkFEOEI0NjIyQUY2MDAzOEI5NUQiLCJ0eXAiOiJKV1QifQ.eyJhY2NvdW50IjoiY29zbWV0aWNzMiIsIndvcmtzcGFjZSI6ImhlbnJpcXVlYmFsYmlubyIsInN1YiI6InZ0ZXguc2VydmljZS1leGFtcGxlQDAuMi4yMiIsInR5cGUiOiJsaW5rIiwidXNlckxvZ2luIjoidnRleC5zZXJ2aWNlLWV4YW1wbGVAMC4yLjIyIiwidXNlcklkIjoibGluazp2dGV4LnNlcnZpY2UtZXhhbXBsZUAwLjIuMjIiLCJyb2xlcyI6WyJsaW5rOnZ0ZXguc2VydmljZS1leGFtcGxlQDAuMi4yMiJdLCJuYmYiOjE2OTE1MTIxNzcsImV4cCI6MTY5MTU5ODU3NywiaWF0IjoxNjkxNTEyMTc3LCJpc3MiOiJ2dGV4aW8vcm91dGVyIiwiYXVkIjoidnRleGlvIn0.

Decoding the app token

Check the content of this token using a platform such as jwt.io. This decoded representation provides valuable details, including the associated account and workspace, user and role information, as well as timestamps for token validity.

node/middlewares/validate.ts

Terminal

DecodedToken


_16{
_16  "account": "myaccount",
_16  "workspace": "myworkspace",
_16  "sub": "vtex.service-example@0.2.22",
_16  "type": "link",
_16  "userLogin": "vtex.service-example@0.2.22",
_16  "userId": "link:vtex.service-example@0.2.22",
_16  "roles": [
_16    "link:vtex.service-example@0.2.22"
_16  ],
_16  "nbf": 1691512177,
_16  "exp": 1691598577,
_16  "iat": 1691512177,
_16  "iss": "vtexio/router",
_16  "aud": "vtexio"
_16}

Logging the app token

To inspect the authToken of an app, go to the node/middlewares/validate.ts file and add the highlighted log code.

Checking the app token

Decoding the app token

node/middlewares/validate.ts


_24import { UserInputError } from '@vtex/api'
_24
_24export async function validate(ctx: Context, next: () => Promise<any>) {
_24  const {
_24    vtex: {
_24      route: { params },
_24    },
_24  } = ctx
_24
_24  console.log(ctx.vtex.authToken)
_24  console.info('Received params:', params)
_24
_24  const { code } = params
_24
_24  if (!code) {
_24    throw new UserInputError('Code is required') // Wrapper for a Bad Request (400) HTTP Error. Check others in https://github.com/vtex/node-vtex-api/blob/fd6139349de4e68825b1074f1959dd8d0c8f4d5b/src/errors/index.ts
_24  }
_24
_24  const codeNumber = parseInt(code as string, 10)
_24
_24  ctx.state.code = codeNumber
_24
_24  await next()
_24}