身份验证
- Authorization: ApiKey
- API 密钥只能放在 POST /api/v1/auth/token 的 Authorization 请求头中。 不要将其放入 JSON、URL 或查询参数。
- Authorization: Bearer
- 资源请求使用返回的令牌，并根据 expires_at 更新；expires_in 的单位为秒。
为什么要先获取令牌？
使用 API 密钥获取令牌。令牌有效期为 15 分钟，可用于多个请求。访问资源时，只需在 Authorization: Bearer 请求头中发送令牌。
普通请求不包含 API 密钥。如果仅令牌泄露，最多只能在其到期前访问资源。但 API 密钥被盗后，仍可能被用来获取新令牌。
令牌的有效期是多久？
- expires_in
- 自签发起 900 秒，即 15 分钟。发送请求不会延长有效期。
- expires_at
- 以 UTC 表示的到期时间。当前的访问限制可能会提前阻止令牌访问。
何时获取新令牌？
对多个请求重复使用同一令牌，并在 expires_at 之前获取新令牌。无需在每次操作前获取令牌。使用 API 密钥获取新令牌。
访问被拒绝与重试
- 401
- 401 并不总是表示令牌已过期。如果已过期，获取新令牌后最多重试读取一次。如果获取令牌返回 401，请检查密钥并停止自动尝试。
- 403
- 遇到 403 时，请检查权限、IP 限制和套餐。获取新令牌不会恢复已撤销的访问权限。
IP 限制
- 访问令牌不能绕过密钥的当前权限、商店权益、撤销状态或 IP 限制。
- 适当情况下，可将密钥限制为集成的源地址。
- 管理员可以编辑此列表；最多允许 32 个地址。
密钥管理
- API 密钥管理与集成的资源权限相互独立。
- 只有 owner 可以向群组授予查看、创建、编辑或删除密钥的管理权限；获授权的群组成员只能执行该群组获授的操作。
速率限制
Engine ≥ 4.143.0. 每次令牌响应都包含签发时店铺策略中的 data.rate_limits。所有密钥共享这些额度；获取新令牌不会重置额度。套餐变更可能在令牌过期前生效。
- read_per_minute
- 每分钟读取请求数。
- write_per_minute
- 每分钟写入请求数；该值不授予写入权限。
- auth_per_minute
- 每分钟令牌请求数，包括失败的身份验证尝试。