跳到主要内容

认证

Shoplazza CLI v2 使用 OAuth 2.0 + PKCE 进行安全认证。本指南涵盖交互式登录、CI/CD 非交互式认证、作用域管理和多店铺工作流。

交互式登录（浏览器）​

标准认证流程通过浏览器进行 OAuth 授权：

shell
shoplazza auth login --store-domain my-store.myshoplaza.com

流程：

  1. CLI 在 Shoplazza 合作伙伴平台创建 OAuth 会话。在交互式终端中，CLI 会先询问你未传入的店铺或业务域
  2. CLI 打印授权 URL，在浏览器中打开即可授权
  3. 授权后，CLI 接收并存储凭证，该店铺成为你的当前 Profile
  4. 凭证加密后保存在 CLI 的配置目录中（操作系统用户配置目录下的 shoplazza-cli/，如 macOS 上的 ~/Library/Application Support/shoplazza-cli/）

不带 --store-domain 时，auth login 只登录账户。选定店铺至少需要一个作用域：传入 --domain 或 --scope，或在提示时选择业务域。

登录时指定作用域​

使用 --domain 请求特定业务域的访问权限：

shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers

或使用 --scope 精细控制 OAuth 作用域：

shell
shoplazza auth login --store-domain my-store.myshoplaza.com --scope read_product,write_product,read_order

每次登录都会替换账户已授权的作用域。如需追加作用域并保留已有的，加上 --merge-scopes：

shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain discounts --merge-scopes

查看可用作用域​

shell
shoplazza auth scopes

非交互式登录（CI/CD）​

在 CI/CD 流水线和自动化环境中，使用用户访问令牌（UAT）：

shell
shoplazza auth login --uat <your-token> --store-domain my-store.myshoplaza.com

或设置 SHOPLAZZA_UAT，auth login 会用它代替 --uat：

shell
export SHOPLAZZA_UAT=your-token
shoplazza auth login --store-domain my-store.myshoplaza.com
shoplazza products +search --keyword "shirt"
提示

在有浏览器的机器上运行一次 shoplazza auth login 即可获得 UAT，登录输出中包含该值（uat）。将其作为密钥存储在 CI/CD 系统中——切勿提交到源代码仓库。

查看认证状态​

shell
shoplazza auth status

显示内容：是否已登录及当前账户、已授权的 OAuth 作用域、UAT 过期时间，以及每个已配置的 Profile（店铺、作用域、令牌状态、是否为当前 Profile）。

切换店铺​

无需注销即可切换到另一个店铺：

shell
shoplazza auth store use --store-domain another-store.myshoplaza.com

CLI 会复用已有的账户凭证为新店铺申请店铺令牌，并创建或复用该店铺的 Profile。如需直接管理 Profile，或用 --profile <名称> 让单条命令操作其他店铺，参见 Profile 管理。

注销​

移除所有 Profile 和存储的凭证（在交互式终端中会先请你确认）：

shell
shoplazza auth logout
警告

注销会删除本机存储的所有令牌和 Profile。下次使用 CLI 时需要重新认证。

作用域映射​

--domain <模块> 会展开为以下作用域：

模块所需作用域
productsread_product, write_product, read_collection, write_collection, read_inventory, write_inventory, read_comments, write_comments, read_gift_cards, write_gift_cards
ordersread_order, write_order
customersread_customer, write_customer
discountsread_price_rules, write_price_rules
shopread_shop, write_shop, read_shop_navigation, write_shop_navigation, read_collection, write_collection, read_product, write_product
themesread_themes, write_themes, read_shop
checkoutread_themes, write_themes
appread_themes, write_themes, read_shop
billing无
webhook无
all以上全部作用域

billing 和 webhook 不带任何作用域，因此只带 --domain billing 或 --domain webhook（且不使用 UAT）的店铺登录会因没有作用域而被拒绝。

如果令牌缺少所需作用域，API 会拒绝调用（HTTP 403），CLI 返回 auth 错误（退出码 3）并提示如何重新认证。

安全最佳实践​

  • 加密存储 — 凭证加密保存在 CLI 的配置目录中，而非明文配置文件
  • 定期轮换令牌 — 定期重新认证以刷新令牌
  • 最小作用域 — 只请求工作流所需的作用域
  • CI/CD 密钥 — 将 UAT 令牌作为加密密钥存储在 CI/CD 系统中
  • 不要提交令牌 — 将 .shoplazza/ 添加到 .gitignore
在此页面