> ## 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 金鑰**（Settings → API Keys）下管理所有金鑰。

## 金鑰的運作方式

金鑰綁定單一公司，並有自己的權限範圍（scope）清單。Alforse 會同時依兩項限制授權每個請求，兩者都允許時請求才會成功：

* 儲存在金鑰上的範圍，以及
* 建立者當下所擁有的權限。

因此金鑰的權限永遠不會超過建立它的人：從建立者移除某項權限，金鑰也會一併失去。其他公司的資料則永遠無法存取。

### 何時需要金鑰，何時不需要

| 用戶端 | 連線方式 |
| - | - |
| Claude.ai、Claude Desktop、ChatGPT | **OAuth**。連線沿用授權使用者的角色與公司，因此不需要金鑰。 |
| Claude Code、Cursor、VS Code、Codex | API 金鑰 |
| 無介面指令碼與 CI | API 金鑰 |
| 僅支援 stdio 的用戶端 | API 金鑰，透過 `mcp-remote` 連線 |

兩種流程的詳細資訊請參閱「驗證」。

## 建立金鑰

Alforse screenshot**Settings → API Keys: the key list with masked previews, scopes, and rate limit, plus the one-time 'You can only see this key once' dialog**

完整金鑰僅會在建立時顯示一次。

1. 前往**設定 → API 金鑰**，選取**新增 API 金鑰**。
2. 輸入**名稱**。名稱在您的公司內必須是唯一的。
3. 可選擇性設定**到期於**。留空則金鑰永不過期。
4. 授予整合所需的範圍，然後儲存。
5. 立即從對話框複製金鑰。同一個對話框也會提供 MCP 連線指令。

該對話框是完整金鑰唯一出現的地方。Alforse 之後會捨棄明文值，只保留 SHA-256 雜湊值，以及供清單顯示的五個字元預覽。由於無法還原原始值，遺失的金鑰只能刪除後重新建立。

HEADS UP

**請將金鑰視同密碼**

金鑰是持有者憑證（bearer secret）：持有它的人就能以其範圍執行動作。請將它存放在密鑰管理工具中，切勿提交到原始碼控制系統。若金鑰外洩，請刪除該金鑰並建立新金鑰來輪替。

## 呼叫 API

每個操作都是對 `https://api.alforse.com` 上 `/api/v1/{module}/{operation}` 的 `POST` 請求，並將金鑰作為 bearer 權杖放在 `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 參考文件包含範例，以及可用於產生用戶端 SDK 的 OpenAPI 規格。

### Data API

Data API 直接透過 REST 公開資料表與檢視。金鑰在此能看到的內容，受到應用程式的列級安全性（row-level security）政策限制。

HEADS UP

**Data API 的寫入會略過服務層**

直接寫入不會重新計算衍生值，例如合計、狀態或分類帳分錄。僅在 Alforse API 沒有對應操作，且您清楚這項變更影響的每一筆記錄時，才透過 Data API 寫入。

## API 金鑰與 Webhook

這兩項功能傳遞流量的方向相反，彼此也互不依賴：

| | 方向 | 使用的密鑰 |
| - | - | - |
| **API 金鑰** | 您的系統呼叫 Alforse | 金鑰本身 |
| **[Webhook](https://docs.alforse.com/zh-Hant/docs/building/webhooks.md)** | 訂閱的記錄變更時，Alforse 呼叫您的系統 | Webhook 自己的簽署密鑰，絕不是 API 金鑰 |

多數整合會將兩者結合：由 webhook 通知有東西改變，整合再使用金鑰讀取最新的記錄。

## 相關內容

**Webhook**

在記錄變更時收到通知，然後用您的金鑰讀取它。

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


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