Back to Details

vtex-io-auth-tokens-and-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auth Tokens & Request Context

认证令牌与请求上下文

When this skill applies

适用场景

Use this skill when the main decision is which VTEX IO identity should authenticate a backend request to VTEX services.
  • Choosing between 
    ctx.authToken
    , 
    ctx.storeUserAuthToken
    , and 
    ctx.adminUserAuthToken
  • Deciding whether a VTEX client call should use 
    AUTH_TOKEN
    , 
    STORE_TOKEN
    , or 
    ADMIN_TOKEN
  • Reviewing storefront and Admin integrations that should respect the current user identity
  • Replacing hardcoded 
    appKey
    and 
    appToken
    usage inside a VTEX IO app
Do not use this skill for:
  • deciding which policies belong in 
    manifest.json
  • modeling route-level authorization or resource-based policies
  • choosing between 
    ExternalClient
    , 
    JanusClient
    , and other client abstractions
  • browser-side login or session UX flows
  • validating route input or deciding what data may cross the app boundary
当你需要确定应该使用哪个VTEX IO身份对发往VTEX服务的后端请求进行认证时，可参考本指南：
  • 在
    ctx.authToken
    、
    ctx.storeUserAuthToken
    和
    ctx.adminUserAuthToken
    之间做选择
  • 确定VTEX客户端调用应该使用
    AUTH_TOKEN
    、
    STORE_TOKEN
    还是
    ADMIN_TOKEN
  • 审核需要遵循当前用户身份规则的店面和管理员集成逻辑
  • 替换VTEX IO应用中硬编码的
    appKey
    和
    appToken
    用法
本指南不适用于以下场景：
  • 确定
    manifest.json
    中应该包含哪些权限策略
  • 设计路由级授权或基于资源的权限策略
  • 在
    ExternalClient
    、
    JanusClient
    和其他客户端抽象之间做选型
  • 浏览器端登录或会话用户体验流程
  • 校验路由输入或确定哪些数据可以跨应用边界传输

Decision rules

决策规则

  • Use this skill to decide which identity talks to VTEX endpoints, not what that identity is authorized to do.
  • Use 
    AUTH_TOKEN
    with 
    ctx.authToken
    only for app-level operations that are not tied to a current shopper or Admin user.
  • Use 
    STORE_TOKEN
    with 
    ctx.storeUserAuthToken
    whenever the action comes from storefront browsing or a shopper-triggered flow and the integration should respect shopper permissions.
  • Use 
    ADMIN_TOKEN
    with 
    ctx.adminUserAuthToken
    whenever the action comes from an Admin interface and the integration should respect the logged-in Admin user's License Manager permissions.
  • Prefer user tokens whenever they are available. The official guidance is to avoid app-token authentication when a store or Admin user token can represent the requester more accurately.
  • If the corresponding user token is not present, fall back to 
    AUTH_TOKEN
    only when the operation is truly app-scoped and does not depend on a current shopper or Admin identity.
  • When using VTEX IO clients that accept 
    authMethod
    , pass the token choice explicitly when the default app identity is not the right one for the request.
  • When wrapping custom VTEX clients, propagate the matching auth token from 
    IOContext
    at the client boundary instead of hardcoding credentials in handlers.
  • Keep token choice aligned with the user journey: storefront flows should not silently escalate to app-level permissions, and Admin flows should not bypass the current Admin role context.
  • ADMIN_TOKEN
    with 
    ctx.adminUserAuthToken
    must remain server-side only and must never be exposed or proxied to browser clients.
  • Treat token choice and policy design as separate concerns: this skill decides which identity is making the call, while auth-and-policies decides what that identity is allowed to do.
  • Do not use 
    appKey
    and 
    appToken
    inside a VTEX IO app unless there is a documented exception outside the normal VTEX IO auth-token model.
  • Never log raw tokens or return them in responses. Tokens are request secrets, and downstream callers should receive only business data.
Token selection at a glance:
TokenContext fieldUse whenAvoid when
AUTH_TOKEN
ctx.authToken
app-level jobs, service-to-service work, or operations not linked to a current usera shopper or Admin user is already driving the action
STORE_TOKEN
ctx.storeUserAuthToken
storefront and shopper-triggered operationsbackend jobs or Admin-only operations
ADMIN_TOKEN
ctx.adminUserAuthToken
Admin requests that must respect the current user's LM rolestorefront flows or background app tasks
  • 本指南用于确定与VTEX端点通信的身份，而非该身份的授权访问范围。
  • 仅当执行与当前购物者或管理员用户无关的应用级操作时，才搭配
    ctx.authToken
    使用
    AUTH_TOKEN
    。
  • 如果操作来自店面浏览或购物者触发的流程，且集成需要遵循购物者权限规则，请搭配
    ctx.storeUserAuthToken
    使用
    STORE_TOKEN
    。
  • 如果操作来自管理员界面，且集成需要遵循已登录管理员用户的许可证管理器权限规则，请搭配
    ctx.adminUserAuthToken
    使用
    ADMIN_TOKEN
    。
  • 只要用户令牌可用就优先使用。官方指引建议：当店面或管理员用户令牌可以更准确地代表请求者时，应避免使用应用令牌认证。
  • 如果没有对应的用户令牌，仅当操作确实属于应用范围、且不依赖当前购物者或管理员身份时，才回退使用
    AUTH_TOKEN
    。
  • 使用支持
    authMethod
    的VTEX IO客户端时，如果默认的应用身份不适合当前请求，请显式传入令牌选择参数。
  • 封装自定义VTEX客户端时，应该在客户端边界从
    IOContext
    传递匹配的认证令牌，而非在处理器中硬编码凭证。
  • 保持令牌选择与用户旅程一致：店面流程不应该静默升级到应用级权限，管理员流程不应该绕过当前管理员角色上下文。
  • 搭配
    ctx.adminUserAuthToken
    使用的
    ADMIN_TOKEN
    必须仅保留在服务端，绝对不能暴露或代理给浏览器客户端。
  • 令牌选择和权限策略设计是独立的关注点：本指南确定调用方身份，而认证与权限相关规则确定该身份的允许操作范围。
  • 除非有正常VTEX IO认证令牌模型之外的 documented 例外情况，否则不要在VTEX IO应用中使用
    appKey
    和
    appToken
    。
  • 绝对不要记录原始令牌，也不要在响应中返回令牌。令牌是请求机密，下游调用方仅应该接收业务数据。
令牌选择速查表：
令牌上下文字段适用场景不适用场景
AUTH_TOKEN
ctx.authToken
应用级任务、服务间通信，或与当前用户无关的操作操作已由购物者或管理员用户触发的场景
STORE_TOKEN
ctx.storeUserAuthToken
店面和购物者触发的操作后端任务或仅管理员可操作的场景
ADMIN_TOKEN
ctx.adminUserAuthToken
需要遵循当前用户LM角色规则的管理员请求店面流程或后台应用任务

Hard constraints

硬性约束

Constraint: User-driven requests must prefer user tokens over the app token

约束：用户驱动的请求必须优先使用用户令牌而非应用令牌

If a request is initiated by a current shopper or Admin user, the VTEX integration MUST use the corresponding user token instead of defaulting to the app token.
Why this matters
Using the app token for user-driven work widens permissions unnecessarily and disconnects the request from the real user context that should govern access.
Detection
If the code runs in a storefront or Admin request path and still uses 
ctx.authToken
or implicit app-token behavior, STOP and verify whether 
ctx.storeUserAuthToken
or 
ctx.adminUserAuthToken
should be used instead.
Correct
typescript
export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.storeUserAuthToken,
      },
    })
  }
}
Wrong
typescript
export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}
如果请求由当前购物者或管理员用户发起，VTEX集成必须使用对应的用户令牌，而不是默认使用应用令牌。
重要性
对用户驱动的操作使用应用令牌会不必要地放大权限，且会将请求与实际应该管控访问权限的用户上下文断开关联。
检测方法
如果代码运行在店面或管理员请求路径中，但仍使用
ctx.authToken
或隐式的应用令牌行为，请立即停下来验证是否应该改用
ctx.storeUserAuthToken
或
ctx.adminUserAuthToken
。
正确示例
typescript
export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.storeUserAuthToken,
      },
    })
  }
}
错误示例
typescript
export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}

Constraint: App tokens must be reserved for app-level operations that are not tied to a user

约束：应用令牌必须仅用于与用户无关的应用级操作

Use 
ctx.authToken
only when the request is genuinely app-scoped and no current shopper or Admin identity should govern the action.
Why this matters
The app token carries the permissions declared in the app manifest. Using it for user-triggered actions can bypass the narrower shopper or Admin permission model that the platform expects.
Detection
If a request originates from an Admin page, storefront interaction, or another user-facing workflow, STOP before using 
ctx.authToken
and confirm that the action is truly app-level rather than user-scoped.
Correct
typescript
export class RatesAndBenefitsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}
Wrong
typescript
export class AdminOrdersClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}
This is wrong when the client is used from an Admin flow that should respect the logged-in user's role.
仅当请求确实属于应用范围、且没有当前购物者或管理员身份需要管控操作时，才可以使用
ctx.authToken
。
重要性
应用令牌携带了应用清单中声明的权限。对用户触发的操作使用应用令牌会绕过平台预期的、权限范围更窄的购物者或管理员权限模型。
检测方法
如果请求来自管理员页面、店面交互或其他面向用户的工作流，在使用
ctx.authToken
前请先停下来确认操作确实属于应用级而非用户范围。
正确示例
typescript
export class RatesAndBenefitsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}
错误示例
typescript
export class AdminOrdersClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.authToken,
      },
    })
  }
}
当这个客户端用于需要遵循已登录用户角色规则的管理员流程时，上述实现是错误的。

Constraint: VTEX IO apps must not hardcode VTEX API credentials when auth tokens are available

约束：有可用认证令牌时，VTEX IO应用不得硬编码VTEX API凭证

A VTEX IO app MUST use tokens from 
IOContext
or 
authMethod
instead of embedding 
appKey
, 
appToken
, or static VTEX credentials in source code or routine runtime configuration.
Why this matters
Hardcoded VTEX credentials are harder to rotate, easier to leak, and bypass the request-context model that VTEX IO clients already support.
Detection
If you see 
X-VTEX-API-AppKey
, 
X-VTEX-API-AppToken
, raw VTEX API credentials, or environment variables carrying permanent VTEX credentials inside a normal IO app integration, STOP and replace them with the correct auth-token flow unless there is a documented exception.
Correct
typescript
await ctx.clients.catalog.getSkuById(id, {
  authMethod: 'ADMIN_TOKEN',
})
Wrong
typescript
await fetch(`https://${ctx.vtex.account}.myvtex.com/api/catalog/pvt/stockkeepingunit/${id}`, {
  headers: {
    'X-VTEX-API-AppKey': process.env.VTEX_APP_KEY!,
    'X-VTEX-API-AppToken': process.env.VTEX_APP_TOKEN!,
  },
})
VTEX IO应用必须使用
IOContext
或
authMethod
提供的令牌，而不能在源代码或常规运行时配置中嵌入
appKey
、
appToken
或静态VTEX凭证。
重要性
硬编码的VTEX凭证轮换难度更高、更容易泄露，且会绕过VTEX IO客户端已支持的请求上下文模型。
检测方法
如果你在常规IO应用集成中看到
X-VTEX-API-AppKey
、
X-VTEX-API-AppToken
、原始VTEX API凭证，或者存储永久VTEX凭证的环境变量，请立即停下来，将其替换为正确的认证令牌流程，除非有documented例外情况。
正确示例
typescript
await ctx.clients.catalog.getSkuById(id, {
  authMethod: 'ADMIN_TOKEN',
})
错误示例
typescript
await fetch(`https://${ctx.vtex.account}.myvtex.com/api/catalog/pvt/stockkeepingunit/${id}`, {
  headers: {
    'X-VTEX-API-AppKey': process.env.VTEX_APP_KEY!,
    'X-VTEX-API-AppToken': process.env.VTEX_APP_TOKEN!,
  },
})

Preferred pattern

推荐模式

Start from the requester context, choose the token identity that matches that requester, and keep the token propagation inside the client layer.
Minimal selection guide:
text
storefront request -> STORE_TOKEN / ctx.storeUserAuthToken
admin request -> ADMIN_TOKEN / ctx.adminUserAuthToken
background app work -> AUTH_TOKEN / ctx.authToken
Pass the token explicitly when the client supports 
authMethod
:
typescript
await ctx.clients.orders.listOrders({
  authMethod: 'ADMIN_TOKEN',
})
typescript
await ctx.clients.orders.listOrders({
  authMethod: 'STORE_TOKEN',
})
Or inject the matching token in a custom VTEX client:
typescript
import type { IOContext, InstanceOptions } from '@vtex/api'
import { JanusClient } from '@vtex/api'

export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.adminUserAuthToken,
      },
    })
  }
}
Keep the decision close to the request boundary, then let downstream handlers and services depend on the correctly configured client rather than choosing tokens ad hoc in many places.
从请求者上下文出发，选择与请求者匹配的令牌身份，并在客户端层完成令牌传递。
极简选择指南：
text
店面请求 -> STORE_TOKEN / ctx.storeUserAuthToken
管理员请求 -> ADMIN_TOKEN / ctx.adminUserAuthToken
后台应用任务 -> AUTH_TOKEN / ctx.authToken
如果客户端支持
authMethod
，请显式传入令牌参数：
typescript
await ctx.clients.orders.listOrders({
  authMethod: 'ADMIN_TOKEN',
})
typescript
await ctx.clients.orders.listOrders({
  authMethod: 'STORE_TOKEN',
})
或者在自定义VTEX客户端中注入匹配的令牌：
typescript
import type { IOContext, InstanceOptions } from '@vtex/api'
import { JanusClient } from '@vtex/api'

export class OmsClient extends JanusClient {
  constructor(ctx: IOContext, options?: InstanceOptions) {
    super(ctx, {
      ...options,
      headers: {
        ...options?.headers,
        VtexIdclientAutCookie: ctx.adminUserAuthToken,
      },
    })
  }
}
将令牌选择逻辑放在靠近请求边界的位置，让下游处理器和服务依赖配置正确的客户端，而不是在多处临时选择令牌。

Common failure modes

常见错误场景

  • Defaulting every VTEX request to 
    ctx.authToken
    , even when a shopper or Admin user initiated the action.
  • Using 
    ctx.authToken
    in Admin pages and accidentally bypassing the current Admin user's License Manager role context.
  • Using 
    ctx.authToken
    in storefront flows that should be limited by shopper permissions.
  • Hardcoding 
    appKey
    and 
    appToken
    in an IO app instead of using auth tokens from 
    IOContext
    .
  • Choosing the right token in one client method but forgetting to apply the same identity consistently across related calls.
  • Mixing token choice with policy modeling and treating them as the same decision.
  • Logging 
    ctx.authToken
    , 
    ctx.storeUserAuthToken
    , or 
    ctx.adminUserAuthToken
    in plain text, or forwarding raw tokens to downstream services that do not need them.
  • 所有VTEX请求默认使用
    ctx.authToken
    ，即使操作是由购物者或管理员用户发起的。
  • 在管理员页面中使用
    ctx.authToken
    ，意外绕过了当前管理员用户的许可证管理器角色上下文。
  • 在应该受购物者权限限制的店面流程中使用
    ctx.authToken
    。
  • 在IO应用中硬编码
    appKey
    和
    appToken
    ，而不是使用
    IOContext
    提供的认证令牌。
  • 在一个客户端方法中选择了正确的令牌，但忘记在相关调用中保持身份一致性。
  • 混淆令牌选择和权限策略设计，将二者视为同一个决策。
  • 明文记录
    ctx.authToken
    、
    ctx.storeUserAuthToken
    或
    ctx.adminUserAuthToken
    ，或者将原始令牌转发给不需要这些令牌的下游服务。

Review checklist

审核检查清单

  • Does each VTEX integration use the correct requester identity: shopper, Admin user, or app?
  • Are 
    ctx.storeUserAuthToken
    and 
    ctx.adminUserAuthToken
    preferred when a user is actually driving the action?
  • Is 
    ctx.authToken
    used only for app-level operations that are not tied to a current user?
  • Are hardcoded VTEX credentials absent from normal IO app integrations?
  • Is token propagation centralized in the client layer or explicit 
    authMethod
    usage rather than scattered across handlers?
  • 每个VTEX集成都使用了正确的请求者身份：购物者、管理员用户还是应用？
  • 当操作确实由用户驱动时，是否优先使用了
    ctx.storeUserAuthToken
    和
    ctx.adminUserAuthToken
    ？
  • ctx.authToken
    是否仅用于与当前用户无关的应用级操作？
  • 常规IO应用集成中是否没有硬编码的VTEX凭证？
  • 令牌传递逻辑是否集中在客户端层或通过显式的
    authMethod
    使用，而不是分散在各个处理器中？

Related skills

相关指南

  • vtex-io-auth-and-policies
     - Use when the main choice is which permissions and policies the chosen identity should carry
  • vtex-io-auth-and-policies
     - 适用于需要确定所选身份应该携带哪些权限和策略的场景

Reference

参考资料