資料架構: 身份驗證

資料架構: 身份驗證. 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

附加欄位: 否