> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 密钥

> 创建一个限定于公司的密钥，让脚本、CI 任务或 AI 编码客户端仅凭您授予的权限调用 Alforse API。

API 密钥让程序无需有人登录即可调用 Alforse。管理员和开发人员为无法完成浏览器登录的脚本、CI 流水线和 AI 编码客户端创建密钥。您可以在**设置 → API密钥**下管理所有密钥。

## 密钥如何工作

密钥绑定到单个公司，并拥有自己的权限范围列表。Alforse 会同时依据两个限制对每个请求授权，只有两者都允许，请求才会成功：

* 密钥上存储的范围，以及
* 其创建者此刻所拥有的权限。

因此密钥的权限永远不会超过创建它的人：撤销创建者的某项权限，密钥也随之失去该权限。其他公司的数据始终无法访问。

### 何时需要密钥，何时不需要

| 客户端 | 连接方式 |
| - | - |
| Claude.ai、Claude Desktop、ChatGPT | **OAuth**。连接沿用授权用户的角色和公司，因此无需密钥。 |
| Claude Code、Cursor、VS Code、Codex | API 密钥 |
| 无界面脚本和 CI | API 密钥 |
| 仅支持 stdio 的客户端 | API 密钥，通过 `mcp-remote` 连接 |

两种流程的详细说明请参见"身份验证"（Authentication）。

## 创建密钥

Alforse screenshot**设置 → API密钥：含掩码预览、范围和速率限制的密钥列表，以及一次性的“您只能看到此密钥一次”对话框**

完整的密钥在创建时只显示一次。

1. 前往**设置 → API密钥**并选择**新建API密钥**。
2. 输入**名称**。它在贵公司内必须唯一。
3. 可选择设置**过期时间**。留空则密钥永不过期。
4. 授予集成所需的范围，然后保存。
5. 立即从对话框中复制密钥。同一个对话框还会给出一条 MCP 连接命令。

该对话框是完整密钥唯一出现的地方。之后 Alforse 会丢弃明文值，只保留 SHA-256 哈希，以及用于列表显示的五个字符的预览。由于无法恢复原始密钥，丢失的密钥必须删除并重新创建。

HEADS UP

**将密钥视同密码**

密钥是持有者凭证：谁持有它，谁就能以其范围执行操作。请将其保存在密钥管理器中，切勿提交到源代码管理。如果泄露，请删除该密钥并创建替代密钥以完成轮换。

## 调用 API

每个操作都是对 `https://api.alforse.com` 上 `/api/v1/{module}/{operation}` 的 `POST` 请求，并将您的密钥作为持有者令牌放在 `Authorization` 标头中。

```http theme={null}
POST /api/v1/{module}/{operation}
Host: api.alforse.com
Authorization: Bearer alf_your_key_here
Content-Type: application/json
```

不需要其他任何东西：密钥没有需要打开的会话，也没有需要续期的令牌。请求到达时，Alforse 会对所出示的密钥计算哈希，查找具有该哈希的已存记录，并确认该密钥未过期且未达到速率限制，然后才会运行该操作。

NOTE

**接受的标头**

请使用 `Authorization: Bearer alf_…`。为了兼容，Alforse 也会从 `alforse-key` 标头读取密钥。API v1 会拒绝任何不是 `alf_` 密钥的凭证；OAuth 连接器访问的是 MCP 端点，而不是 API v1。

## 权限、套餐和速率限制

### 范围

每个范围的写法为 `module_action`，例如 `sales_view` 或 `inventory_create`。只授予集成会用到的范围：没有任何范围的密钥可以通过身份验证，但既不能读取也不能写入数据。范围的修改以及密钥的删除，从下一个请求起即生效。

### 套餐

密钥仅适用于使用 **Business** 或 **Partner** 套餐的公司（功能 `API_KEYS`）。在 Starter 套餐上，无论密钥拥有哪些范围，每个请求都会返回 `403`。

### 速率限制

| 设置 | 值 |
| - | - |
| 新密钥的默认值 | **每分钟 60 个请求**（窗口 `1m`） |
| 平台策略可设置的其他窗口 | `1h`、`1d` |
| 计数方式 | 按密钥 |
| 在哪里查看 | 密钥列表的**速率限制**列 |

应用中没有设置该限制的选项；如果某个集成确实需要更多，请联系 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 直接公开表和视图。密钥在此能看到的内容受应用行级安全策略限制。

HEADS UP

**Data API 的写入会跳过服务层**

直接写入不会重新计算合计、状态或分类账分录等派生值。只有当 Alforse API 没有对应的操作，并且您清楚该变更会影响的每一条记录时，才通过 Data API 写入。

## API 密钥与 Webhook

这两项功能的流量方向相反，彼此互不依赖：

| | 方向 | 使用的密钥 |
| - | - | - |
| **API 密钥** | 您的系统调用 Alforse | 密钥本身 |
| **[Webhook](https://docs.alforse.com/zh/docs/building/webhooks.md)** | 订阅的记录发生变化时，Alforse 调用您的系统 | Webhook 自己的签名密钥，绝不是 API 密钥 |

大多数集成会将二者结合：Webhook 发出发生变化的信号，随后集成使用密钥读取最新的记录。

## 相关内容

**Webhook**

在记录变化时收到通知，然后用您的密钥读取它。

[Open](https://docs.alforse.com/zh/docs/building/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.