認證 (Authentication)

概述

AICC API 採用 Token 認證機制，所有 HTTP API 請求都需要在 Header 中包含有效的 accessToken。Token 通過登入 API 獲取，使用者密碼通過 SHA256 加密後傳輸。

登入 API

請求方式

POST /api/login
Content-Type: application/json

請求參數

參數名	型別	必填	說明
username	string	是	使用者名稱
password	string	是	SHA256 加密後的密碼
loginType	integer	否	登入類型 (1: 座席, 2: 監督者, 3: 管理員)

密碼加密說明

1. 使用 SHA256 演算法對明文密碼進行加密
2. 輸出十六進制字符串格式
3. 示例：
   • 明文密碼：123456
   • SHA256 加密後：8d969eef6ecad3c29a3a873fba5f4a900f7ce49b052a20a6cfe13b69855e7e6

請求範例

{
  "username": "agent001",
  "password": "8d969eef6ecad3c29a3a873fba5f4a900f7ce49b052a20a6cfe13b69855e7e6",
  "loginType": 1
}

成功回應範例

{
  "code": 0,
  "message": "success",
  "data": {
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

回應字段說明

字段名	型別	說明
accessToken	string	存取令牌，用於後續 API 呼叫
expiresIn	integer	Token 有效期，單位為秒 (通常為 3600 秒 / 1 小時)
tokenType	string	Token 類型，固定為 "Bearer"

Token 使用

在請求 Header 中使用 Token

所有後續的 HTTP API 請求都需要在 Authorization Header 中包含有效的 Token：

Authorization: Bearer {accessToken}

請求範例

curl -X GET "https://api.aicc.com/api/task/list" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

Token 失效處理

當 Token 失效或過期時，API 會回傳 401 Unauthorized 錯誤：

{
  "code": 401,
  "message": "Token expired or invalid"
}

此時應該：

1. 重新呼叫登入 API 獲取新的 Token
2. 使用新的 Token 重試原請求

安全建議

1. 密碼加密：永遠不要以明文形式傳輸密碼，必須使用 SHA256 加密
2. HTTPS 傳輸：所有 API 呼叫應使用 HTTPS 加密連線
3. Token 保管：不要將 Token 暴露在客戶端代碼或日誌中
4. 定期更新：在 Token 即將過期時主動重新登入獲取新 Token
5. 環境隔離：在測試和生產環境中使用不同的憑證和 Token

常見錯誤

錯誤碼	說明	解決方案
401	Token 無效或已過期	重新登入獲取新 Token
403	權限不足	確認使用者權限或 loginType 設定
400	密碼加密格式錯誤	驗證 SHA256 加密結果格式
500	伺服器錯誤	聯絡技術支援