> ## 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.

# 認證

> 使用 Bearer Token 認證帳獸 API 請求

## 認證方式

帳獸 API 使用 **Bearer Token** 進行認證。每個 API 請求都必須在 `Authorization` 標頭中附帶有效的 Token。

```
Authorization: Bearer YOUR_API_TOKEN
```

## 取得 Token

你可以在後台的**金鑰管理**頁面建立 API Token。詳見 [API 金鑰管理](/guides/api-keys)。

<Note>
  Token 只會在建立時顯示一次，請立即複製並妥善保存。
</Note>

## 使用範例

<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>

## 認證失敗

如果 Token 無效、已過期或未提供，API 會回傳 `401 Unauthorized`：

```json theme={null}
{
  "message": "Unauthenticated."
}
```

### 常見原因

| 原因          | 說明                                        |
| ----------- | ----------------------------------------- |
| 未附帶 Token   | 請求未包含 `Authorization` 標頭                  |
| Token 格式錯誤  | 確認格式為 `Bearer YOUR_TOKEN`（注意 Bearer 後有空格） |
| Token 已撤銷   | Token 已被手動撤銷，需建立新的                        |
| Token 已重新生成 | 重新生成後舊 Token 立即失效                         |

## Token 權限

每個 Token 包含以下 abilities：

| 權限                    | 說明         | 對應端點                                                                           |
| --------------------- | ---------- | ------------------------------------------------------------------------------ |
| `customers:read`      | 讀取客戶資料     | `GET /customers`, `GET /customers/{id}`                                        |
| `customers:write`     | 建立、更新、刪除客戶 | `POST /customers`, `PUT /customers/{id}`, `DELETE /customers/{id}`             |
| `orders:read`         | 讀取訂單資料     | `GET /orders`, `GET /orders/{orderNo}`, `GET /orders/stats`                    |
| `orders:write`        | 建立訂單       | `POST /orders`                                                                 |
| `subscriptions:read`  | 讀取訂閱資料     | `GET /subscriptions`, `GET /subscriptions/{id}`                                |
| `subscriptions:write` | 建立、更新、刪除訂閱 | `POST /subscriptions`, `PUT /subscriptions/{id}`, `DELETE /subscriptions/{id}` |

如果你的 Token 沒有對應的權限，API 會回傳 `403 Forbidden`。

## 安全建議

<Tip>
  * 將 Token 存放在環境變數中，不要寫在程式碼裡
  * 不要在前端（瀏覽器）使用 Token
  * 不要將 Token 提交到版本控制系統
  * 定期輪換 Token，特別是在人員異動時
</Tip>