Shopify Admin API

Shopify Admin API 401 错误排查指南

问题轮廓#

401 表示未通过身份验证,优先查 access token 是否过期或未放入 Authorization 头。另外,确认用的是 Admin API 令牌而不是 Storefront 令牌。另外,自定义应用在 Dev Dashboard 或后台开发应用里轮换密钥后,旧令牌立即失效。

技术解释#

GraphQL 与 REST 的鉴权头格式以现行 shopify.dev 为准,勿混用私有应用已淘汰说明。随后,用最简单的 shop { name } 查询验证令牌本身是否可用。随后,时间漂移过大可能导致部分 HMAC 场景失败,服务器应对时 NTP。

落地步骤#

  1. 记录返回的 WWW-Authenticate 或错误正文,避免只看状态码。
  2. 测试与生产店铺令牌分开,防拷错 .env。
  3. Partner 应用安装范围变更后需重新授权。
  4. 401 连续出现时应暂停重试,以免被限流掩盖根因。

复核清单#

工单附请求 ID 与 Asia/Shanghai 时间。验收阶段,勿在前端暴露 Admin 令牌。

专项深读 · 可复现排查指南

401 与 403 的鉴权排查顺序

出现 401 时先确认请求使用的是正确应用的访问令牌、正确店铺和匹配版本的 Admin API;不要把 Admin token 放进浏览器 JavaScript。

建议按以下顺序复现和定位

  1. 确认请求发送到正确的 myshopify.com 域名,检查 API 路径与版本。
  2. 用服务器端环境变量管理访问令牌,检查 X-Shopify-Access-Token 的值是否为空或过期。
  3. 区分令牌失效(常见 401)和作用域不足(可能返回 403 或 GraphQL 错误),不要仅看 HTTP 状态。
  4. 确认卸载/重装 App 后旧令牌是否仍被缓存。
  5. 给日志记录 shop 域名、请求 ID、HTTP 状态和 GraphQL errors,掩码处理令牌。

可参考的示例(非真实客户环境)

curl -X POST \
  'https://YOUR-STORE.myshopify.com/admin/api/2026-10/graphql.json' \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: YOUR_SERVER_SIDE_TOKEN' \
  --data '{"query":"{ shop { name } }"}'
# 仅在受保护的服务端环境运行;不要把真实令牌写进工单。
注意:有效但缺少权限的令牌不应通过反复重试解决;需要检查应用实际授权的 scopes 与重新授权流程。

交付与验证记录应该包含什么

以只读 query 先确认身份与店铺一致,再测试需要的业务接口,不应在诊断阶段进行高风险写入。

原始技术资料:Shopify / Google 官方文档。本节为根据公开文档整理的排查方法与模拟示例,未宣称来自客户项目或已在您的店铺实测。

本文由 风格技术 技术团队整理,适用于 Shopify 标准版与 Plus 店铺。Shopify 平台能力迭代较快,具体操作路径与字段以官方文档和店铺后台实际版本为准。