API 權限（API Permissions）

什麼是 API 權限

API 權限（API Permissions）決定「一個 API 客戶端可以調用哪些介面」。

例如某個系統擁有 Customer Read，那麼它可以透過 API 讀取客戶資訊；如果沒有 Customer Write，則不能透過 API 修改客戶資料。

因此，API 權限可以獨立控制 Read、Write、Create、Update、Delete、Send、Execute、Manage 等不同介面能力。

API 權限與後台權限的區別

後台功能權限面向 Finger Manager 後台用戶，決定員工登入後台後可以使用哪些功能。例如 Operations 用戶可以發布公告。

API 權限面向外部系統、應用程式或服務，決定透過 API 可以訪問哪些系統能力。例如某個 CRM 系統可以讀取客戶資料，但不能讀取交易信號。

兩套權限可以獨立管理。擁有 Finger Manager 後台權限，並不代表自動擁有 API 權限。

01　建立 API 訪問憑證

在使用 API 前，需要為對應系統建立獨立的 API 訪問憑證。

根據接入方式，可能包括 API Key、API Secret、Client ID、Client Secret、Access Token、Certificate、OAuth Credential 或其他認證資訊。

每一個 API 客戶端建議使用獨立憑證。例如 CRM System 使用一組 API Credential，Trading System 使用另一組 API Credential，External Reporting System 再使用獨立 Credential。這樣可以分別管理每個系統的訪問範圍。

02　為 API 客戶端配置權限

03　讀取權限（Read）

Read 權限允許 API 客戶端讀取指定類型的數據。

例如 Market Data Read、Product Read、Customer Read、Account Read、Order Read、Position Read、Trade History Read、Notification Read。Read 權限通常只允許取得數據，不允許修改。

04　寫入權限（Write）

Write 權限允許 API 客戶端修改或提交業務數據。

例如 Customer Write、Product Write、Account Write、Order Write、Notification Write。

由於 Write 權限可能直接影響業務數據，因此通常需要比 Read 權限更嚴格地控制。

05　建立權限（Create）

部分介面可以進一步區分建立操作。

例如 Customer Create、Order Create、Notification Create、User Create。如果系統只擁有讀取權限，則無法透過 API 建立新的業務記錄。

06　更新權限（Update）

Update 權限用於控制外部系統是否可以修改已經存在的數據。

例如某 CRM 系統可以擁有 Customer Read + Customer Update，允許同步客戶聯絡方式或其他指定欄位，但不一定擁有 Customer Delete。

07　刪除權限（Delete）

Delete 屬於高風險 API 權限，通常不建議預設開放。

例如 Customer Delete、Product Delete、Notification Delete。

對於訂單、交易歷史、日誌等關鍵數據，系統可以完全不提供永久刪除 API。需要刪除能力時，應根據具體業務和風險單獨授權。

08　訂單 API 權限

對於交易系統接入，可以對訂單相關 API 單獨設定權限。

例如 Order Read、Order Create、Order Update、Order Cancel、Order History Read。不同外部系統可以獲得不同能力。行情 App 可以只有 Order Read 或完全沒有訂單權限，交易執行系統可以擁有 Order Create、Order Cancel、Order Read。

09　持倉 API 權限

持倉相關權限可以包括 Position Read、Position History Read、Position Export。

對於只需要顯示客戶持倉的系統，可以只授予 Position Read。如果外部系統不需要交易數據，則無需授予相關權限。

10　交易信號 API 權限

Finger Manager 中的交易信號可以透過 API 進行讀取和處理。

相關權限可以包括 Trading Signal Read、Trading Signal Receive、Trading Signal Forward、Trading Signal Manage。

例如，外部風險管理系統可以讀取即時交易信號，再根據機構業務規則進行處理。對於需要透過 Finger Bridge 轉發交易信號的場景，也可以單獨設定相應訪問權限。

11　客戶 API 權限

客戶相關 API 可以分別控制 Customer Read、Customer Create、Customer Update、Customer Status Read、Customer Status Manage。

例如外部 CRM 可以讀取客戶資料，KYC / KYB 系統可以更新審核狀態，而其他系統則不一定需要訪問完整客戶資訊。

12　產品 API 權限

產品相關介面可以設定 Product Read、Product Create、Product Update、Product Status Manage、Market Read。

例如 Finger Trader 前端可以透過 API 取得產品列表、產品基礎資料、交易時間、價格精度和產品狀態，但通常不需要獲得產品後台管理權限。

13　通知 API 權限

外部系統也可以透過 API 調用 Finger Manager 的通知能力。

例如 Notification Create、Notification Send、Push Send、In-App Notification Send、Email Send、SMS Send。

例如某個業務系統檢測到客戶帳戶狀態發生變化後，可以透過 API 自動觸發 App 內通知 + Push Notification，無需營運人員手動進入 Finger Manager。

14　報表 API 權限

機構可以允許外部分析或報表系統透過 API 取得數據。

例如 Report Read、Trading Report Read、Customer Report Read、Billing Report Read。

這類 API 通常建議只提供讀取權限，不提供修改能力。

15　API 與數據權限

API 權限同樣可以與數據權限結合。

例如某個 API Credential 擁有 Order Read，但數據權限為 Japan Entity，那麼該 API 只能讀取 Japan Entity 的訂單。即使介面本身支援其他組織數據，也不會返回超出權限範圍的內容。

因此，完整的 API 訪問能力可以理解為：API 功能權限 + 數據權限。

16　組織級 API 權限

API Credential 可以綁定到指定 Organization。

例如 Japan API 只能訪問 Japan Entity；Hong Kong API 只能訪問 Hong Kong Entity。集團級系統則可以根據授權擁有多個組織的數據訪問範圍。

這種方式可以防止不同業務主體之間透過 API 相互訪問數據。

17　唯讀 API

對於第三方系統或數據分析工具，可以建立唯讀 API Credential。

唯讀 API 只允許 Read，不允許 Write、Update、Delete、Execute。

例如 BI System 擁有 Customer Report Read、Order Read、Position Read，但無法對 Finger Manager 中的數據進行任何修改。

18　內部系統 API

19　第三方系統接入

當機構需要連接第三方系統時，建議為每個第三方建立獨立 API Credential。

例如 CRM Vendor、Market Data Vendor、Reporting Vendor、Liquidity Provider、Broker、Custodian、Compliance System。

不要讓多個第三方共同使用同一套 API 憑證。這樣可以單獨控制權限，也方便後續停用某一項整合。

20　API Credential 狀態

21　憑證輪換

出於安全考慮，可以定期更換 API Secret、Token 或其他訪問憑證。

常見流程為：舊 Credential → 生成新 Credential → 更新外部系統 → 確認新憑證工作正常 → 撤銷舊憑證。

這種方式可以降低長期使用固定密鑰帶來的安全風險。

22　IP 限制

對於重要 API，可以進一步設定允許訪問的 IP 地址。

例如只允許 Broker Internal Server 對應的固定 IP 調用 API，來自其他 IP 的請求將被拒絕。

這可以作為 API Credential 之外的額外安全控制。

23　介面範圍限制

除了權限名稱，也可以限制 Credential 只能訪問特定 API Endpoint。

例如允許 GET /orders、GET /positions，但不允許 POST /orders。

即使屬於同一個訂單模組，也可以分別控制讀取和執行能力。

24　調用頻率限制

API 可以根據系統配置設定 Rate Limit。

例如每秒請求數、每分鐘請求數、每日請求額度、並發連接數量。

不同 API 客戶端可以使用不同限制。這樣可以降低異常請求或錯誤程式對系統穩定性的影響。

25　敏感 API 權限

部分 API 權限屬於高敏感權限，應嚴格控制。

例如 Order Create、Order Cancel、Customer Update、Permission Manage、User Manage、Notification Bulk Send、API Credential Manage、System Settings、Trading Signal Forward。

這些權限建議只授予明確需要的內部系統或經過審核的連接方。

26　API 權限與角色權限獨立

API 權限與 Finger Manager 後台用戶角色可以完全獨立。

例如某後台用戶是 Operations，擁有後台通知管理權限，但這並不意味著該用戶擁有 Notification API 訪問權限。

相反，一個外部系統可能擁有 API 權限，但沒有任何 Finger Manager 後台登入帳戶。這種分離可以避免後台帳戶和系統介面權限混用。

27　API 調用日誌

Finger Manager 可以記錄 API 的調用情況。

例如 Credential、Client ID、API Endpoint、請求時間、請求來源 IP、請求方法、響應狀態和執行結果。

對於關鍵操作，還可以記錄相關業務對象。例如某 API 在 14:30:22 調用 Order Cancel，操作訂單 ORDER-100234。

透過 API 日誌，可以協助機構進行審計和問題排查。

28　異常訪問處理

如果發現異常 API 調用，可以 Disable Credential、Revoke Token、修改權限、調整 Rate Limit、限制 IP 或更換 API Secret。

透過這些方式，可以快速阻止異常系統繼續訪問。

29　API 最小權限原則

API 同樣建議按照最小權限原則（Principle of Least Privilege）配置。

例如行情系統只需要 Market Data Read，則不應該授予 Order Write；報表系統只需要 Report Read，則不應該擁有 Customer Update。

每一個 API Credential 都只擁有完成其業務所必需的權限。

API 權限管理邏輯

API 權限管理邏輯可以理解為：建立 API Credential → 確定所屬 Organization → 選擇需要開放的 API → 配置 Read / Write / Execute 等權限 → 設定數據訪問範圍 → 配置 IP / Rate Limit 等安全策略 → 向外部系統提供 Credential → 外部系統調用 API → Finger Manager 驗證 Credential → 檢查 API 權限 → 檢查數據權限 → 執行請求或拒絕訪問 → 記錄 API 調用日誌。

典型應用場景