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 调用日志。

典型应用场景