数据架构: 身份验证

数据架构: 身份验证. API 接收或返回的数据字段、类型和约束。

数据架构

获取 · 令牌 — 身份验证 — 响应

ApiResponse_TokenData_ · API 接收或返回的数据字段、类型和约束。

dataTokenData 必填: 响应示例 · TokenData.

示例: {"access_token":"EXAMPLE_ACCESS_TOKEN","expires_at":"2026-01-01T12:15:00Z","expires_in":1800,"permissions":["orders.order:read"],"rate_limits":{"auth_per_minute":1,"read_per_minute":2,"write_per_minute":15},"token_type":"Bearer","warnings":[]}
metaContextPageMeta ContextMeta PageMeta RequestMeta 必填: 响应元数据。

示例: {"request_id":"example"}

附加字段: 否

撤销令牌 · ApiResponse

ApiResponse_TokenRevokedData_ · API 接收或返回的数据字段、类型和约束。

dataTokenRevokedData 必填: 响应示例 · TokenRevokedData.

示例: {"revoked":true}
metaContextPageMeta ContextMeta PageMeta RequestMeta 必填: 响应元数据。

示例: {"request_id":"example-request"}

附加字段: 否

获取 · 令牌 — 身份验证 — 响应

TokenData · API 接收或返回的数据字段、类型和约束。

access_token字符串必填: 用于 Authorization: Bearer 请求头的令牌。运行独立示例前，请设置 SHOPENTLY_ACCESS_TOKEN。

示例: "EXAMPLE_ACCESS_TOKEN"
expires_at字符串必填: 以 UTC 表示的到期时间。当前的访问限制可能会提前阻止令牌访问。

format: "date-time"

示例: "2026-01-01T12:15:00Z"
expires_in整数必填: 实际有效期，以秒计；本例请求 1800 秒。请求不会延长有效期。expires_at 表示 UTC 到期时间。

minimum: 300maximum: 3600

示例: 1800
permissions数组 <字符串> 必填: permissions 列出当前有效权限，即密钥、创建者及商店套餐权限的交集，包括已启用插件的权限。每次请求都会重新检查访问权限。

示例: ["orders.order:read"]
rate_limitsTokenRateLimitsData 必填: Engine ≥ 4.143.0. 每次令牌响应都包含签发时店铺策略中的 data.rate_limits。所有密钥共享这些额度；获取新令牌不会重置额度。套餐变更可能在令牌过期前生效。

示例: {"auth_per_minute":1,"read_per_minute":2,"write_per_minute":15}
token_type字符串可选: Bearer. 返回令牌使用的身份验证方案。

const: "Bearer"

默认值: "Bearer"示例: "Bearer"
warnings数组 <TokenLifetimeWarning > 必填: 超出范围的整数使用 900 秒，并在 warnings 中返回 token.ttl_out_of_range 及指向 learn.shopently.com 的 documentation_url。省略字段不产生警告；类型错误返回 422。

示例: []

附加字段: 否

TokenLifetimeWarning

TokenLifetimeWarning · 超出范围的整数使用 900 秒，并在 warnings 中返回 token.ttl_out_of_range 及指向 learn.shopently.com 的 documentation_url。省略字段不产生警告；类型错误返回 422。

applied_seconds整数可选: 900 s (15 min)

默认值: 900
code字符串可选: token.ttl_out_of_range

const: "token.ttl_out_of_range"

默认值: "token.ttl_out_of_range"
documentation_url字符串可选: https://learn.shopently.com/en/api/docs/authentication/#token-lifetime

默认值: "https://learn.shopently.com/en/api/docs/authentication/#token-lifetime"
field字符串可选: ttl_seconds

const: "ttl_seconds"

默认值: "ttl_seconds"
max_seconds整数可选: 3600 s (60 min)

默认值: 3600
message字符串可选: 超出范围的整数使用 900 秒，并在 warnings 中返回 token.ttl_out_of_range 及指向 learn.shopently.com 的 documentation_url。省略字段不产生警告；类型错误返回 422。

默认值: "ttl_seconds must be between 300 and 3600 seconds. The default lifetime of 900 seconds was applied."
min_seconds整数可选: 300 s (5 min)

默认值: 300

附加字段: 否

速率限制

TokenRateLimitsData · Engine ≥ 4.143.0. 每次令牌响应都包含签发时店铺策略中的 data.rate_limits。所有密钥共享这些额度；获取新令牌不会重置额度。套餐变更可能在令牌过期前生效。零表示不可用，而不是无限制。

auth_per_minute整数必填: 每分钟的令牌签发和撤销请求数，包括认证失败。两个操作共用 auth 限额。

minimum: 0maximum: 1000000

示例: 1
read_per_minute整数必填: 每分钟读取请求数。

minimum: 0maximum: 1000000

示例: 2
write_per_minute整数必填: 每分钟写入请求数；该值不授予写入权限。

minimum: 0maximum: 1000000

示例: 15

附加字段: 否

获取 · 令牌 — 身份验证 — 请求体

TokenRequest · API 接收或返回的数据字段、类型和约束。

ttl_seconds整数可选: 可选整数 ttl_seconds：300–3600 秒（5–60 分钟）。省略时默认为 900 秒（15 分钟）。

默认值: 900示例: 1800

附加字段: 否

撤销令牌 · TokenRevokeRequest

TokenRevokeRequest · 发送 POST /api/v1/auth/revoke，在 Authorization: ApiKey 中提供签发密钥，在 JSON 的 access_token 中提供令牌。成功后再次使用返回 401。重复、未知或其他密钥的令牌均返回相同的 revoked: true；不会删除其他密钥的令牌。

access_token字符串必填: 发送 POST /api/v1/auth/revoke，在 Authorization: ApiKey 中提供签发密钥，在 JSON 的 access_token 中提供令牌。成功后再次使用返回 401。重复、未知或其他密钥的令牌均返回相同的 revoked: true；不会删除其他密钥的令牌。

minLength: 1maxLength: 256

示例: "shpt_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

附加字段: 否

撤销令牌 · TokenRevokedData

TokenRevokedData · 发送 POST /api/v1/auth/revoke，在 Authorization: ApiKey 中提供签发密钥，在 JSON 的 access_token 中提供令牌。成功后再次使用返回 401。重复、未知或其他密钥的令牌均返回相同的 revoked: true；不会删除其他密钥的令牌。

revoked布尔值可选: 发送 POST /api/v1/auth/revoke，在 Authorization: ApiKey 中提供签发密钥，在 JSON 的 access_token 中提供令牌。成功后再次使用返回 401。重复、未知或其他密钥的令牌均返回相同的 revoked: true；不会删除其他密钥的令牌。

const: true

默认值: true示例: true

附加字段: 否