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:

Token	Context field	Use when	Avoid when
`AUTH_TOKEN`	`ctx.authToken`	app-level jobs, service-to-service work, or operations not linked to a current user	a shopper or Admin user is already driving the action
`STORE_TOKEN`	`ctx.storeUserAuthToken`	storefront and shopper-triggered operations	backend jobs or Admin-only operations
`ADMIN_TOKEN`	`ctx.adminUserAuthToken`	Admin requests that must respect the current user's LM role	storefront 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

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

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

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

Reference

参考资料

App authentication using auth tokens - Official token model for
```
AUTH_TOKEN
```
,
```
STORE_TOKEN
```
, and
```
ADMIN_TOKEN
```
Using VTEX IO clients - Client usage patterns that complement token selection
Policies - How app-token permissions relate to manifest-declared policies

使用认证令牌的应用认证 -
```
AUTH_TOKEN
```
、
```
STORE_TOKEN
```
和
```
ADMIN_TOKEN
```
的官方令牌模型说明
使用VTEX IO客户端 - 与令牌选择互补的客户端使用模式
权限策略 - 应用令牌权限与清单声明的权限策略的关联说明

vtex-io-auth-tokens-and-context

Original

Translation

Auth Tokens & Request Context

认证令牌与请求上下文

When this skill applies

适用场景

Decision rules

决策规则

Hard constraints

硬性约束

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

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

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

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

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

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

Preferred pattern

推荐模式

Common failure modes

常见错误场景

Review checklist

审核检查清单

Related skills

相关指南

Reference

参考资料