> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zangsho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 金鑰管理

> 建立、重新生成與撤銷 API Token，管理 API 存取權限

## 概覽

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

## 建立新金鑰

<Steps>
  <Step title="進入金鑰管理頁面">
    登入後台，點擊導覽列的 🔑 圖示進入**金鑰管理**頁面。
  </Step>

  <Step title="建立金鑰">
    點擊**建立新金鑰**按鈕。
  </Step>

  <Step title="複製 Token">
    系統會產生一組 API Token 並顯示在頁面上。

    <Warning>
      Token **只會顯示一次**，請立即複製並妥善保存。關閉對話框後將無法再次查看完整 Token。
    </Warning>
  </Step>
</Steps>

## Token 屬性

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

## 重新生成金鑰

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

<Steps>
  <Step title="進入金鑰管理頁面">
    點擊導覽列的 🔑 圖示。
  </Step>

  <Step title="重新生成">
    點擊**重新生成金鑰**按鈕。
  </Step>

  <Step title="確認操作">
    輸入確認文字以確認操作。

    <Warning>
      重新生成後，**舊的 Token 會立即失效**。所有使用舊 Token 的 API 請求將回傳 401 Unauthorized。請確保更新所有整合中的 Token。
    </Warning>
  </Step>

  <Step title="複製新 Token">
    複製並保存新產生的 Token。
  </Step>
</Steps>

## 撤銷金鑰

如果你不再需要 API 存取，可以撤銷 Token：

1. 進入**金鑰管理**頁面
2. 點擊**撤銷金鑰**
3. 輸入確認文字以確認操作

<Warning>
  撤銷後 Token 立即失效且無法恢復。如需再次使用 API，必須建立新的 Token。
</Warning>

## Token 權限

每個 Token 包含以下 abilities（權限），控制可存取的 API 資源：

| 權限                    | 說明         |
| --------------------- | ---------- |
| `customers:read`      | 讀取客戶資料     |
| `customers:write`     | 建立、更新、刪除客戶 |
| `orders:read`         | 讀取訂單資料     |
| `orders:write`        | 建立訂單       |
| `subscriptions:read`  | 讀取訂閱資料     |
| `subscriptions:write` | 建立、更新、刪除訂閱 |

<Info>
  目前建立的 Token 預設包含所有權限。未來版本可能支援自訂權限範圍。
</Info>

## 角色權限

後台操作金鑰管理的權限依角色而異：

| 操作     | 管理員 | 一般用戶 |
| ------ | --- | ---- |
| 查看金鑰資訊 | ✅   | ✅    |
| 建立金鑰   | ✅   | ❌    |
| 重新生成金鑰 | ✅   | ❌    |
| 撤銷金鑰   | ✅   | ❌    |

## 使用 Token

在所有 API 請求中，將 Token 放入 `Authorization` 標頭：

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.zangsho.com/v1/customers \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Accept: application/json"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.zangsho.com/v1/customers', {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Accept': 'application/json'
    }
  });

  const data = await response.json();
  ```

  ```php PHP (Laravel) theme={null}
  $response = Http::withToken('YOUR_API_TOKEN')
      ->acceptJson()
      ->get('https://api.zangsho.com/v1/customers');

  $customers = $response->json();
  ```
</CodeGroup>

## 安全最佳實踐

<AccordionGroup>
  <Accordion title="使用環境變數儲存 Token">
    不要將 Token 直接寫在程式碼中，使用環境變數管理：

    ```bash .env theme={null}
    ZANGSHO_API_TOKEN=your_api_token_here
    ```
  </Accordion>

  <Accordion title="限制 Token 曝露範圍">
    * **不要**將 Token 提交到版本控制（Git）
    * **不要**在前端程式碼中使用 Token
    * **不要**在日誌中記錄完整 Token
    * 將 `.env` 加入 `.gitignore`
  </Accordion>

  <Accordion title="定期輪換 Token">
    建議定期重新生成 Token，特別是在以下情況：

    * 團隊成員離職
    * Token 可能已外洩
    * 安全稽核要求
  </Accordion>

  <Accordion title="監控 API 使用情況">
    定期檢查 API 請求日誌，留意異常的存取模式。如果發現可疑活動，立即重新生成或撤銷 Token。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="API 認證" icon="lock" href="/api-reference/authentication">
    了解 API 認證的技術細節。
  </Card>

  <Card title="快速開始" icon="rocket" href="/quickstart">
    使用 Token 發出你的第一個 API 請求。
  </Card>
</CardGroup>