Skip to main content

​
概覽

帳獸使用 Bearer Token 認證 API 請求。每個商家同時只能持有一把有效的 API Token。你可以在後台的金鑰管理頁面（導覽列 🔑 圖示）進行 Token 管理。

​
建立新金鑰

1

進入金鑰管理頁面

登入後台，點擊導覽列的 🔑 圖示進入金鑰管理頁面。
2

建立金鑰

點擊建立新金鑰按鈕。
3

複製 Token

系統會產生一組 API Token 並顯示在頁面上。
Token 只會顯示一次，請立即複製並妥善保存。關閉對話框後將無法再次查看完整 Token。

​
Token 屬性

屬性說明
有效期限永不過期
數量限制每個商家同時只能有一把有效 Token
建立新 Token 時如果已有有效 Token，必須先撤銷才能建立新的

​
重新生成金鑰

如果你需要更換 Token（例如 Token 可能外洩），可以重新生成：
1

進入金鑰管理頁面

點擊導覽列的 🔑 圖示。
2

重新生成

點擊重新生成金鑰按鈕。
3

確認操作

輸入確認文字以確認操作。
重新生成後，舊的 Token 會立即失效。所有使用舊 Token 的 API 請求將回傳 401 Unauthorized。請確保更新所有整合中的 Token。
4

複製新 Token

複製並保存新產生的 Token。

​
撤銷金鑰

如果你不再需要 API 存取，可以撤銷 Token：
  1. 進入金鑰管理頁面
  2. 點擊撤銷金鑰
  3. 輸入確認文字以確認操作
撤銷後 Token 立即失效且無法恢復。如需再次使用 API，必須建立新的 Token。

​
Token 權限

每個 Token 包含以下 abilities（權限），控制可存取的 API 資源：
權限說明
customers:read讀取客戶資料
customers:write建立、更新、刪除客戶
orders:read讀取訂單資料
orders:write建立訂單
subscriptions:read讀取訂閱資料
subscriptions:write建立、更新、刪除訂閱
目前建立的 Token 預設包含所有權限。未來版本可能支援自訂權限範圍。

​
角色權限

後台操作金鑰管理的權限依角色而異：
操作管理員一般用戶
查看金鑰資訊✅✅
建立金鑰✅❌
重新生成金鑰✅❌
撤銷金鑰✅❌

​
使用 Token

在所有 API 請求中，將 Token 放入 Authorization 標頭： 
curl -X GET https://api.zangsho.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

​
安全最佳實踐

不要將 Token 直接寫在程式碼中，使用環境變數管理：
.env
ZANGSHO_API_TOKEN=your_api_token_here
  • 不要將 Token 提交到版本控制（Git）
  • 不要在前端程式碼中使用 Token
  • 不要在日誌中記錄完整 Token
  • 將 .env 加入 .gitignore
建議定期重新生成 Token，特別是在以下情況：
  • 團隊成員離職
  • Token 可能已外洩
  • 安全稽核要求
定期檢查 API 請求日誌，留意異常的存取模式。如果發現可疑活動，立即重新生成或撤銷 Token。

​
下一步

API 認證

了解 API 認證的技術細節。

快速開始

使用 Token 發出你的第一個 API 請求。