密钥如何工作
密钥绑定到单个公司，并拥有自己的权限范围列表。Alforse 会同时依据两个限制对每个请求授权，只有两者都允许，请求才会成功：- 密钥上存储的范围，以及
- 其创建者此刻所拥有的权限。
何时需要密钥，何时不需要
两种流程的详细说明请参见”身份验证”（Authentication）。
创建密钥
- 前往设置 → API密钥并选择新建API密钥。
- 输入名称。它在贵公司内必须唯一。
- 可选择设置过期时间。留空则密钥永不过期。
- 授予集成所需的范围，然后保存。
- 立即从对话框中复制密钥。同一个对话框还会给出一条 MCP 连接命令。
调用 API
每个操作都是对https://api.alforse.com 上 /api/v1/{module}/{operation} 的 POST 请求，并将您的密钥作为持有者令牌放在 Authorization 标头中。
权限、套餐和速率限制
范围
每个范围的写法为module_action，例如 sales_view 或 inventory_create。只授予集成会用到的范围：没有任何范围的密钥可以通过身份验证，但既不能读取也不能写入数据。范围的修改以及密钥的删除，从下一个请求起即生效。
套餐
密钥仅适用于使用 Business 或 Partner 套餐的公司（功能API_KEYS）。在 Starter 套餐上，无论密钥拥有哪些范围，每个请求都会返回 403。
速率限制
应用中没有设置该限制的选项；如果某个集成确实需要更多，请联系 Alforse 支持。密钥一旦超出限制，请求将收到
429（Rate limit exceeded），并附带 Retry-After 和 X-RateLimit-* 标头。请按 Retry-After 的间隔暂停，然后重新发送请求。
选择 API
有了密钥，您可以使用两种接口中的任意一种。请先使用 Alforse API，仅当 Alforse API 没有提供某个操作时，才退而使用 Data API。Alforse API（推荐）
对 Alforse API 的调用会经过服务层。该层会校验您的输入、强制执行权限，并更新变更所影响的任何派生数据。- 同一操作，两种传输方式。一个操作在 HTTP（
POST /api/v1/{module}/{operation}）和 MCP 上接受相同的参数。 - 风险标签。每个操作都标有
READ、WRITE或DESTRUCTIVE，客户端因此可在执行风险较高的操作前请求确认。 - 参考与 SDK。API 参考包含示例和一份 OpenAPI 规范，可用于生成客户端 SDK。
Data API
Data API 通过 REST 直接公开表和视图。密钥在此能看到的内容受应用行级安全策略限制。API 密钥与 Webhook
这两项功能的流量方向相反，彼此互不依赖：
大多数集成会将二者结合：Webhook 发出发生变化的信号，随后集成使用密钥读取最新的记录。